diff --git a/Frameworks/SDL3.xcframework/Info.plist b/Frameworks/SDL3.xcframework/Info.plist index a89f873..e4b0c2e 100644 --- a/Frameworks/SDL3.xcframework/Info.plist +++ b/Frameworks/SDL3.xcframework/Info.plist @@ -4,23 +4,6 @@ AvailableLibraries - - BinaryPath - SDL3.framework/SDL3 - LibraryIdentifier - ios-arm64_x86_64-simulator - LibraryPath - SDL3.framework - SupportedArchitectures - - arm64 - x86_64 - - SupportedPlatform - ios - SupportedPlatformVariant - simulator - BinaryPath SDL3.framework/SDL3 @@ -35,6 +18,21 @@ SupportedPlatform ios + + BinaryPath + SDL3.framework/Versions/A/SDL3 + LibraryIdentifier + macos-arm64_x86_64 + LibraryPath + SDL3.framework + SupportedArchitectures + + arm64 + x86_64 + + SupportedPlatform + macos + BinaryPath SDL3.framework/SDL3 @@ -68,9 +66,9 @@ BinaryPath - SDL3.framework/Versions/A/SDL3 + SDL3.framework/SDL3 LibraryIdentifier - macos-arm64_x86_64 + ios-arm64_x86_64-simulator LibraryPath SDL3.framework SupportedArchitectures @@ -79,7 +77,9 @@ x86_64 SupportedPlatform - macos + ios + SupportedPlatformVariant + simulator CFBundlePackageType diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/sdl3-config.cmake b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/SDL3Config.cmake similarity index 98% rename from Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/sdl3-config.cmake rename to Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/SDL3Config.cmake index 784d27d..03673f3 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/sdl3-config.cmake +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/SDL3Config.cmake @@ -59,7 +59,7 @@ if(NOT TARGET SDL3::SDL3-shared) set_target_properties(SDL3::SDL3-shared PROPERTIES FRAMEWORK "TRUE" - IMPORTED_LOCATION "${_sdl3_framework_path}/SDL3" + IMPORTED_LOCATION "${_sdl3_framework_path}" INTERFACE_LINK_LIBRARIES "SDL3::Headers" COMPATIBLE_INTERFACE_BOOL "SDL3_SHARED" INTERFACE_SDL3_SHARED "ON" diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/sdl3-config-version.cmake b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/SDL3ConfigVersion.cmake similarity index 100% rename from Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/sdl3-config-version.cmake rename to Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/CMake/SDL3ConfigVersion.cmake diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL.h index c963394..861c404 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -20,9 +20,12 @@ */ /** - * \file SDL.h + * Main include header for the SDL library, version 3.2.0 * - * Main include header for the SDL library, version 3.1.2 + * It is almost always best to include just this one header instead of + * picking out individual headers included here. There are exceptions to + * this rule--SDL_main.h is special and not included here--but usually + * letting SDL.h include the kitchen sink for you is the correct approach. */ #ifndef SDL_h_ @@ -30,6 +33,7 @@ #include #include +#include #include #include #include @@ -65,6 +69,7 @@ #include #include #include +#include #include #include #include @@ -76,6 +81,7 @@ #include #include #include +#include #include #include #include diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_assert.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_assert.h index f5f798e..09b3b47 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_assert.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_assert.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,9 +51,14 @@ * - It provides statistics and data on all failed assertions to the app. * - It allows the default assertion handler to be controlled with environment * variables, in case an automated script needs to control it. + * - It can be used as an aid to Clang's static analysis; it will treat SDL + * assertions as universally true (under the assumption that you are serious + * about the asserted claims and that your debug builds will detect when + * these claims were wrong). This can help the analyzer avoid false + * positives. * - * To use it: do a debug build and just sprinkle around tests to check your - * code! + * To use it: compile a debug build and just sprinkle around tests to check + * your code! */ #ifndef SDL_assert_h_ @@ -84,7 +89,7 @@ extern "C" { * - 3: Paranoid settings: All SDL assertion macros enabled, including * SDL_assert_paranoid. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors @@ -113,24 +118,27 @@ extern "C" { * * If the program is not running under a debugger, SDL_TriggerBreakpoint will * likely terminate the app, possibly without warning. If the current platform - * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro - * does nothing. + * isn't supported, this macro is left undefined. * - * \threadsafety It is safe to call this function from any thread. + * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner -#elif defined(_MSC_VER) +#elif 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) #include #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__)) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) @@ -147,18 +155,40 @@ extern "C" { #include #define SDL_TriggerBreakpoint() raise(SIGTRAP) #else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ #endif -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FUNCTION __FUNCTION__ + +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ # define SDL_FUNCTION __func__ #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) # define SDL_FUNCTION __FUNCTION__ #else # define SDL_FUNCTION "???" #endif + +/** + * A macro that reports the current file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FILE __FILE__ + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_LINE __LINE__ /* @@ -176,14 +206,50 @@ This also solves the problem of... disable assertions. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro for wrapping code in `do {} while (0);` without compiler warnings. + * + * Visual Studio with really aggressive warnings enabled needs this to avoid + * compiler complaints. + * + * the `do {} while (0);` trick is useful for wrapping code in a macro that + * may or may not be a single statement, to avoid various C language + * accidents. + * + * To use: + * + * ```c + * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0)); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NULL_WHILE_LOOP_CONDITION (0) + +#elif defined(_MSC_VER) /* Avoid /W4 warnings. */ /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking this condition isn't constant. And looks like an owl's face! */ -#ifdef _MSC_VER /* stupid /W4 warnings. */ #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) #else #define SDL_NULL_WHILE_LOOP_CONDITION (0) #endif +/** + * The macro used when an assertion is disabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is disabled (perhaps in a release build). + * + * The code does nothing, but wraps `condition` in a sizeof operator, which + * generates no code and has no side effects, but avoid compiler warnings + * about unused variables. + * + * \param condition the condition to assert (but not actually run here). + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -198,7 +264,7 @@ disable assertions. * condition, try to break in a debugger, kill the program, or ignore the * problem). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AssertState { @@ -216,11 +282,11 @@ typedef enum SDL_AssertState * used by the assertion handler, then added to the assertion report. This is * returned as a linked list from SDL_GetAssertionReport(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AssertData { - SDL_bool always_ignore; /**< SDL_TRUE if app should always continue when assertion is triggered. */ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ const char *condition; /**< A string of this assert's test code. */ const char *filename; /**< The source file where this assert lives. */ @@ -232,7 +298,7 @@ typedef struct SDL_AssertData /** * Never call this directly. * - * Use the SDL_assert* macros instead. + * Use the SDL_assert macros instead. * * \param data assert data structure. * \param func function name. @@ -240,29 +306,57 @@ typedef struct SDL_AssertData * \param line line number. * \returns assert state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN; -/* Define the trigger breakpoint call used in asserts */ -#ifndef SDL_AssertBreakpoint -#if defined(ANDROID) && defined(assert) -/* Define this as empty in case assert() is defined as SDL_assert */ -#define SDL_AssertBreakpoint() -#else + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The macro used when an assertion triggers a breakpoint. + * + * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint + * instead. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() -#endif + +#elif !defined(SDL_AssertBreakpoint) +# if defined(ANDROID) && defined(assert) + /* Define this as empty in case assert() is defined as SDL_assert */ +# define SDL_AssertBreakpoint() +# else +# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() +# endif #endif /* !SDL_AssertBreakpoint */ -/* the do {} while(0) avoids dangling else problems: - if (x) SDL_assert(y); else blah(); - ... without the do/while, the "else" could attach to this macro's "if". - We try to handle just the minimum we need here in a macro...the loop, - the static vars, and break points. The heavy lifting is handled in - SDL_ReportAssertion(), in SDL_assert.c. -*/ +/** + * The macro used when an assertion is enabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is enabled. + * + * The `do {} while(0)` avoids dangling else problems: + * + * ```c + * if (x) SDL_assert(y); else blah(); + * ``` + * + * ... without the do/while, the "else" could attach to this macro's "if". We + * try to handle just the minimum we need here in a macro...the loop, the + * static vars, and break points. The heavy lifting is handled in + * SDL_ReportAssertion(). + * + * \param condition the condition to assert. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ @@ -305,7 +399,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; } @@ -336,7 +432,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_release(condition) SDL_disabled_assert(condition) @@ -363,7 +461,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) @@ -389,7 +489,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * #endif /** - * An assertion test that always performed. + * An assertion test that is always performed. * * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You * almost never want to use this, as it could trigger on an end-user's system, @@ -405,7 +505,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_always(condition) SDL_enabled_assert(condition) @@ -418,7 +520,10 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. * - * \since This datatype is available since SDL 3.0.0. + * \threadsafety This callback may be called from any thread that triggers an + * assert at any time. + * + * \since This datatype is available since SDL 3.2.0. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( const SDL_AssertData *data, void *userdata); @@ -440,7 +545,9 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * fails or NULL for the default handler. * \param userdata a pointer that is passed to `handler`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -459,7 +566,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler( * \returns the default SDL_AssertionHandler that is called when an assert * triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -482,7 +591,9 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler( * was passed to SDL_SetAssertionHandler(). * \returns the SDL_AssertionHandler that is called when an assert triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAssertionHandler */ @@ -508,9 +619,15 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void ** * ``` * * \returns a list of all failed assertions or NULL if the list is empty. This - * memory should not be modified or freed by the application. + * memory should not be modified or freed by the application. This + * pointer remains valid until the next call to SDL_Quit() or + * SDL_ResetAssertionReport(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads calling + * SDL_ResetAssertionReport() simultaneously, may render the + * returned pointer invalid. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetAssertionReport */ @@ -524,7 +641,11 @@ extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); * no items. In addition, any previously-triggered assertions will be reset to * a trigger_count of zero, and their always_ignore state will be false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads triggering an + * assertion, or simultaneously calling this function may cause + * memory leaks or crashes. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionReport */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_asyncio.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_asyncio.h new file mode 100644 index 0000000..b36cb07 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/* WIKI CATEGORY: AsyncIO */ + +/** + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + */ + +#ifndef SDL_asyncio_h_ +#define SDL_asyncio_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOTaskType +{ + SDL_ASYNCIO_TASK_READ, /**< A read operation. */ + SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */ + SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */ +} SDL_AsyncIOTaskType; + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOResult +{ + SDL_ASYNCIO_COMPLETE, /**< request was completed without error */ + SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */ + SDL_ASYNCIO_CANCELED /**< request was canceled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AsyncIOOutcome +{ + SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + void *buffer; /**< buffer where data was read/written. */ + Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + void *userdata; /**< pointer provided by the app when starting the task */ +} SDL_AsyncIOOutcome; + +/** + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode); + +/** + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); + +/** + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); + +/** + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome); + +/** + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS); + +/** + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_asyncio_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_atomic.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_atomic.h index f159bcd..03e3fb1 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_atomic.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_atomic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -88,15 +88,16 @@ typedef int SDL_SpinLock; * doing. Please be careful using any sort of spinlock!*** * * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. + * \returns true if the lock succeeded, false if the lock is already held. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_UnlockSpinlock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); /** * Lock a spin lock by setting it to a non-zero value. @@ -106,7 +107,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockSpinlock * \sa SDL_UnlockSpinlock @@ -123,7 +126,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_TryLockSpinlock @@ -147,9 +152,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -166,7 +172,50 @@ extern __inline void SDL_CompilerBarrier(void); #endif /** - * Insert a memory release barrier. + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); + +/** + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Insert a memory release barrier (macro version). * * Memory barriers are designed to prevent reads and writes from being * reordered by the compiler and being seen out of order on multi-core CPUs. @@ -186,31 +235,47 @@ extern __inline void SDL_CompilerBarrier(void); * For more information on these semantics, take a look at the blog post: * http://preshing.com/20120913/acquire-and-release-semantics * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierReleaseFunction to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() /** - * Insert a memory acquire barrier. + * Insert a memory acquire barrier (macro version). * - * Please refer to SDL_MemoryBarrierReleaseFunction for the details! + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. * - * \threadsafety Obviously this function is safe to use from any thread at any + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_MemoryBarrierReleaseFunction + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -/* !!! FIXME: this should have documentation! */ -#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) +#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") #elif defined(__GNUC__) && defined(__aarch64__) @@ -225,8 +290,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); hard-coded at address 0xffff0fa0 */ typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() #else #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") @@ -276,9 +341,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * * \threadsafety This macro is safe to use from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay + #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */ #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__) @@ -303,9 +369,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * A type representing an atomic integer value. * * This can be used to manage a value that is synchronized across multiple - * CPUs without a race condition; when an app sets a value with SDL_AtomicSet - * all other threads, regardless of the CPU it is running on, will see that - * value when retrieved with SDL_AtomicGet, regardless of CPU caches, etc. + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. * * This is also useful for atomic compare-and-swap operations: a thread can * change the value as long as its current value matches expectations. When @@ -316,14 +383,14 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * this!). * * This is a struct so people don't accidentally use numeric operations on it - * directly. You have to use SDL_Atomic* functions. + * directly. You have to use SDL atomic functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - * \sa SDL_AtomicAdd + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt */ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; @@ -336,15 +403,16 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; * \param a a pointer to an SDL_AtomicInt variable to be modified. * \param oldval the old value. * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. + * \returns true if the atomic variable was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, int oldval, int newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); /** * Set an atomic variable to a value. @@ -360,11 +428,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicGet + * \sa SDL_GetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); /** * Get the value of an atomic variable. @@ -377,11 +445,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicSet + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); /** * Add to an atomic variable. @@ -397,12 +465,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef * \sa SDL_AtomicIncRef */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); #ifndef SDL_AtomicIncRef @@ -414,11 +482,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to an SDL_AtomicInt to increment. * \returns the previous value of the atomic variable. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef */ -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) #endif #ifndef SDL_AtomicDecRef @@ -429,16 +499,103 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * ***Note: If you don't know what this macro is for, you shouldn't use it!*** * * \param a a pointer to an SDL_AtomicInt to increment. - * \returns SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise. + * \returns true if the variable reached zero after decrementing, false + * otherwise. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicIncRef */ -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) #endif +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***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 oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * 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. + * \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.2.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***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. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + /** * Set a pointer to a new value if it is currently an old value. * @@ -448,17 +605,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to a pointer. * \param oldval the old pointer value. * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. + * \returns true if the pointer was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGetPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, void *oldval, void *newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); /** * Set a pointer to a value atomically. @@ -472,12 +629,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicGetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); /** * Get the value of a pointer atomically. @@ -490,12 +647,12 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicGetPointer(void **a); +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_audio.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_audio.h index b7a4b7b..9569382 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_audio.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_audio.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -33,8 +33,9 @@ * even if the data format changes on either side halfway through. * * An app opens an audio device and binds any number of audio streams to it, - * feeding more data to it as available. When the devices needs more data, it - * will pull it from all bound streams and mix them together for playback. + * feeding more data to the streams as available. When the device needs more + * data, it will pull it from all bound streams and mix them together for + * playback. * * Audio streams can also use an app-provided callback to supply data * on-demand, which maps pretty closely to the SDL2 audio model. @@ -43,6 +44,45 @@ * if you aren't reading from a file) as a basic means to load sound data into * your program. * + * ## Logical audio devices + * + * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a + * logical device ID that you can bind audio streams to. In almost all cases, + * logical devices can be used anywhere in the API that a physical device is + * normally used. However, since each device opening generates a new logical + * device, different parts of the program (say, a VoIP library, or + * text-to-speech framework, or maybe some other sort of mixer on top of SDL) + * can have their own device opens that do not interfere with each other; each + * logical device will mix its separate audio down to a single buffer, fed to + * the physical device, behind the scenes. As many logical devices as you like + * can come and go; SDL will only have to open the physical device at the OS + * level once, and will manage all the logical devices on top of it + * internally. + * + * One other benefit of logical devices: if you don't open a specific physical + * device, instead opting for the default, SDL can automatically migrate those + * logical devices to different hardware as circumstances change: a user + * plugged in headphones? The system default changed? SDL can transparently + * migrate the logical devices to the correct physical device seamlessly and + * keep playing; the app doesn't even have to know it happened if it doesn't + * want to. + * + * ## Simplified audio + * + * As a simplified model for when a single source of audio is all that's + * needed, an app can use SDL_OpenAudioDeviceStream, which is a single + * function to open an audio device, create an audio stream, bind that stream + * to the newly-opened device, and (optionally) provide a callback for + * obtaining audio data. When using this function, the primary interface is + * the SDL_AudioStream and the device handle is mostly hidden away; destroying + * a stream created through this function will also close the device, stream + * bindings cannot be changed, etc. One other quirk of this is that the device + * is started in a _paused_ state and must be explicitly resumed; this is + * partially to offer a clean migration for SDL2 apps and partially because + * the app might have to do more setup before playback begins; in the + * non-simplified form, nothing will play until a stream is bound to a device, + * so they start _unpaused_. + * * ## Channel layouts * * Audio data passing through SDL is uncompressed PCM data, interleaved. One @@ -73,7 +113,7 @@ * - 4 channels (quad) layout: FL, FR, BL, BR * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be - * BL, BR) + * SL, SR) * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR * @@ -94,7 +134,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -102,19 +141,73 @@ extern "C" { #endif -/* masks for different parts of SDL_AudioFormat. */ +/** + * Mask of bits in an SDL_AudioFormat that contains the format bit size. + * + * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BITSIZE (0xFFu) + +/** + * Mask of bits in an SDL_AudioFormat that contain the floating point flag. + * + * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_FLOAT (1u<<8) + +/** + * Mask of bits in an SDL_AudioFormat that contain the bigendian flag. + * + * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN + * instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12) + +/** + * Mask of bits in an SDL_AudioFormat that contain the signed data flag. + * + * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_SIGNED (1u<<15) -#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \ - (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) +/** + * Define an SDL_AudioFormat value. + * + * SDL does not support custom audio formats, so this macro is not of much use + * externally, but it can be illustrative as to what the various bits of an + * SDL_AudioFormat mean. + * + * For example, SDL_AUDIO_S32LE looks like this: + * + * ```c + * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32) + * ``` + * + * \param signed 1 for signed data, 0 for unsigned data. + * \param bigendian 1 for bigendian data, 0 for littleendian data. + * \param flt 1 for floating point data, 0 for integer data. + * \param size number of bits per sample. + * \returns a format value in the style of SDL_AudioFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \ + (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) /** * Audio format. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_AUDIO_BITSIZE * \sa SDL_AUDIO_BYTESIZE @@ -144,17 +237,18 @@ typedef enum SDL_AudioFormat /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ -} SDL_AudioFormat; -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_AUDIO_S16 SDL_AUDIO_S16LE -#define SDL_AUDIO_S32 SDL_AUDIO_S32LE -#define SDL_AUDIO_F32 SDL_AUDIO_F32LE -#else -#define SDL_AUDIO_S16 SDL_AUDIO_S16BE -#define SDL_AUDIO_S32 SDL_AUDIO_S32BE -#define SDL_AUDIO_F32 SDL_AUDIO_F32BE -#endif + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; /** @@ -167,7 +261,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) @@ -181,7 +275,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) @@ -195,7 +289,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) @@ -209,7 +303,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) @@ -223,7 +317,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) @@ -237,7 +331,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) @@ -251,7 +345,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) @@ -265,7 +359,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) @@ -275,7 +369,7 @@ typedef enum SDL_AudioFormat * * Zero is used to signify an invalid/null device. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_AudioDeviceID; @@ -286,7 +380,7 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu) @@ -297,14 +391,14 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu) /** * Format specifier for audio data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AudioFormat */ @@ -326,7 +420,7 @@ typedef struct SDL_AudioSpec * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) @@ -350,7 +444,7 @@ typedef struct SDL_AudioSpec * more of them, bind them to an opened audio device, and feed data to them * (or for recording, consume data from them). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -359,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream; /* Function prototypes */ -/** - * \name Driver discovery functions - * - * These functions return the list of built in audio drivers, in the - * order that they are normally initialized by default. - */ -/* @{ */ - /** * Use this function to get the number of built-in audio drivers. * @@ -384,7 +470,7 @@ typedef struct SDL_AudioStream SDL_AudioStream; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDriver */ @@ -408,12 +494,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. @@ -427,7 +512,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); @@ -453,7 +538,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioRecordingDevices @@ -482,7 +567,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioPlaybackDevices @@ -498,11 +583,10 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioPlaybackDevices * \sa SDL_GetAudioRecordingDevices - * \sa SDL_GetDefaultAudioInfo */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); @@ -532,14 +616,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI * \param spec on return, will be filled with device details. * \param sample_frames pointer to store device buffer size, in sample frames. * Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); /** * Get the current channel map of an audio device. @@ -558,7 +642,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -633,13 +717,52 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseAudioDevice * \sa SDL_GetAudioDeviceFormat */ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec); +/** + * Determine if an audio device is physical (instead of logical). + * + * An SDL_AudioDeviceID that represents physical hardware is a physical + * device; there is one for each piece of hardware that SDL can see. Logical + * devices are created by calling SDL_OpenAudioDevice or + * SDL_OpenAudioDeviceStream, and while each is associated with a physical + * device, there can be any number of logical devices on one physical device. + * + * For the most part, logical and physical IDs are interchangeable--if you try + * to open a logical device, SDL understands to assign that effort to the + * underlying physical device, etc. However, it might be useful to know if an + * arbitrary device ID is physical or logical. This function reports which. + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a physical device, false if it is logical. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid); + +/** + * Determine if an audio device is a playback device (instead of recording). + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a playback device, false if it is recording. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid); + /** * Use this function to pause audio playback on a specified device. * @@ -659,17 +782,17 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioDevice * \sa SDL_AudioDevicePaused */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to unpause audio playback on a specified device. @@ -687,17 +810,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev) * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AudioDevicePaused * \sa SDL_PauseAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to query if an audio device is paused. @@ -710,16 +833,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev * IDs will report themselves as unpaused here. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. + * \returns true if device is valid and paused, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Get the gain of an audio device. @@ -738,7 +861,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioDeviceGain */ @@ -753,8 +876,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * Audio devices default to a gain of 1.0f (no change in output). * * Physical devices may not have their gain changed, only logical devices, and - * this function will always return -1 when used on physical devices. While it - * might seem attractive to adjust several logical devices at once in this + * this function will always return false when used on physical devices. While + * it might seem attractive to adjust several logical devices at once in this * way, it would allow an app or library to interfere with another portion of * the program's otherwise-isolated devices. * @@ -767,17 +890,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \param devid the audio device on which to change gain. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDeviceGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); /** * Close a previously-opened audio device. @@ -794,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID de * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice */ @@ -819,23 +942,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * Binding a stream to a device will set its output format for playback * devices, and its input format for recording devices, so they match the * device's settings. The caller is welcome to change the other end of the - * stream's format at any time. + * stream's format at any time with SDL_SetAudioStreamFormat(). * * \param devid an audio device to bind a stream to. * \param streams an array of audio streams to bind. * \param num_streams number streams listed in the `streams` array. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams); /** * Bind a single audio stream to an audio device. @@ -845,18 +968,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devi * * \param devid an audio device to bind a stream to. * \param stream an audio stream to bind to a device. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); /** * Unbind a list of audio streams from their audio devices. @@ -867,16 +990,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid * * Unbinding a stream that isn't bound to a device is a legal no-op. * - * \param streams an array of audio streams to unbind. + * \param streams an array of audio streams to unbind. Can be NULL or contain + * NULL. * \param num_streams number streams listed in the `streams` array. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams */ -extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams); /** * Unbind a single audio stream from its audio device. @@ -884,11 +1008,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **stream * This is a convenience function, equivalent to calling * `SDL_UnbindAudioStreams(&stream, 1)`. * - * \param stream an audio stream to unbind from a device. + * \param stream an audio stream to unbind from a device. Can be NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream */ @@ -907,7 +1031,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream * \sa SDL_BindAudioStreams @@ -924,7 +1048,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_GetAudioStreamData @@ -943,7 +1067,9 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream); @@ -953,17 +1079,17 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * \param stream the SDL_AudioStream to query. * \param src_spec where to store the input audio format; ignored if NULL. * \param dst_spec where to store the output audio format; ignored if NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); /** * Change the input and output formats of an audio stream. @@ -978,23 +1104,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *s * next sound file, and start putting that new data while the previous sound * file is still queued, and everything will still play back correctly. * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * * \param stream the stream the format is being changed. * \param src_spec the new format of the audio input; if NULL, it is not * changed. * \param dst_spec the new format of the audio output; if NULL, it is not * changed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFormat * \sa SDL_SetAudioStreamFrequencyRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** * Get the frequency ratio of an audio stream. @@ -1006,7 +1138,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *s * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFrequencyRatio */ @@ -1027,18 +1159,18 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \param stream the stream the frequency ratio is being changed. * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 * and 100. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Get the gain of an audio stream. @@ -1055,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioS * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGain */ @@ -1074,17 +1206,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \param stream the stream on which the gain is being changed. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); /** * Get the current input channel map of an audio stream. @@ -1104,7 +1236,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *str * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1128,7 +1260,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStr * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1148,8 +1280,12 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * Data that was previously queued in the stream will still be operated on in * the order that was current when it was added, which is to say you can put @@ -1164,26 +1300,31 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Set the current output channel map of an audio stream. @@ -1194,12 +1335,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * The output channel map reorders data that leaving a stream via * SDL_GetAudioStreamData. * - * Each item in the array represents an output channel, and its value is the + * Each item in the array represents an input channel, and its value is the * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * The output channel map can be changed at any time, as output remapping is * applied during SDL_GetAudioStreamData. @@ -1211,26 +1356,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Add data to the stream. @@ -1246,21 +1398,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_Audi * \param stream the stream the audio data is being added to. * \param buf a pointer to the audio data to add. * \param len the number of bytes to write to the stream. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but if the * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_FlushAudioStream * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); /** * Get converted/resampled data from the stream. @@ -1284,7 +1436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *str * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_GetAudioStreamAvailable @@ -1311,7 +1463,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamData * \sa SDL_PutAudioStreamData @@ -1322,6 +1474,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str /** * Get the number of bytes currently queued. * + * This is the number of bytes put into a stream as input, not the number that + * can be retrieved as output. Because of several details, it's not possible + * to calculate one number directly from the other. If you need to know how + * much usable data can be retrieved right now, you should use + * SDL_GetAudioStreamAvailable() and not this function. + * * Note that audio streams can change their input format at any time, even if * there is still data queued in a different format, so the returned byte * count will not necessarily match the number of _sample frames_ available. @@ -1344,7 +1502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_ClearAudioStream @@ -1361,16 +1519,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * input, so the complete output becomes available. * * \param stream the audio stream to flush. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** * Clear any pending data in the stream. @@ -1379,19 +1537,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *strea * stream until more is added. * * \param stream the audio stream to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamAvailable * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); /** * Use this function to pause audio playback on the audio device associated @@ -1406,16 +1564,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *strea * loading, etc. * * \param stream the audio stream associated with the audio device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); /** * Use this function to unpause audio playback on the audio device associated @@ -1426,16 +1584,36 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream * to progress again, and audio can be generated. * * \param stream the audio stream associated with the audio device to resume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to query if an audio device associated with a stream is + * paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * \param stream the audio stream associated with the audio device to query. + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream); + /** * Lock an audio stream for serialized access. @@ -1454,16 +1632,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream * all the same attributes (recursive locks are allowed, etc). * * \param stream the audio stream to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); /** @@ -1472,17 +1650,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream * This unlocks an audio stream after a call to SDL_LockAudioStream. * * \param stream the audio stream to unlock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety You should only call this from the same thread that * previously called SDL_LockAudioStream. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); /** * A callback that fires when data passes through an SDL_AudioStream. @@ -1519,7 +1697,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stre * is called, so your callback does not need to manage the lock * explicitly. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback * \sa SDL_SetAudioStreamPutCallback @@ -1561,16 +1739,16 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * from the stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamPutCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** * Set a callback that runs when data is added to an audio stream. @@ -1610,16 +1788,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStre * stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** @@ -1637,7 +1815,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStre * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -1699,7 +1877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamDevice * \sa SDL_ResumeAudioStreamDevice @@ -1737,7 +1915,7 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_Audi * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioPostmixCallback */ @@ -1788,14 +1966,14 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio * \param devid the ID of an opened audio device. * \param callback a callback function to be called. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); /** @@ -1839,7 +2017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * Example: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); + * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len); * ``` * * Note that the SDL_LoadWAV function does this same thing for you, but in a @@ -1850,19 +2028,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * ``` * * \param src the data source for the WAVE data. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE * data's format details on successful return. * \param audio_buf a pointer filled with the audio data, allocated by the * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1871,12 +2049,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Loads a WAV from a file path. @@ -1884,7 +2062,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * This is a convenience function that is effectively the same as: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), SDL_TRUE, spec, audio_buf, audio_len); + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); * ``` * * \param path the file path of the WAV file to open. @@ -1894,11 +2072,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1907,12 +2085,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Mix audio data in a specified format. @@ -1941,14 +2119,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * \param len the length of the audio buffer in bytes. * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full * audio volume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); /** * Convert some audio data of one format to another format. @@ -1971,14 +2149,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, * which should be freed with SDL_free(). On error, it will be * NULL. * \param dst_len will be filled with the len of dst_data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); /** * Get the human readable name of an audio format. @@ -1989,7 +2167,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); @@ -2005,7 +2183,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_begin_code.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_begin_code.h index f418c61..a6b47cf 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_begin_code.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_begin_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,15 @@ /* WIKI CATEGORY: BeginCode */ /** - * SDL_begin_code.h sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * # CategoryBeginCode + * + * `SDL_begin_code.h` sets things up for C dynamic library function + * definitions, static inlined functions, and structures aligned at 4-byte + * alignment. If you don't like ugly C preprocessor code, don't look at this + * file. :) + * + * SDL's headers use this; applications generally should not include this + * header directly. */ /* This shouldn't be nested -- included it around code only. */ @@ -33,6 +39,259 @@ #endif #define SDL_begin_code_h +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a symbol as deprecated. + * + * A function is marked deprecated by adding this macro to its declaration: + * + * ```c + * extern SDL_DEPRECATED int ThisFunctionWasABadIdea(void); + * ``` + * + * Compilers with deprecation support can give a warning when a deprecated + * function is used. This symbol may be used in SDL's headers, but apps are + * welcome to use it for their own interfaces as well. + * + * SDL, on occasion, might deprecate a function for various reasons. However, + * SDL never removes symbols before major versions, so deprecated interfaces + * in SDL3 will remain available until SDL4, where it would be expected an app + * would have to take steps to migrate anyhow. + * + * On compilers without a deprecation mechanism, this is defined to nothing, + * and using a deprecated function will not generate a warning. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEPRECATED __attribute__((deprecated)) + +/** + * A macro to tag a symbol as a public API. + * + * SDL uses this macro for all its public functions. On some targets, it is + * used to signal to the compiler that this function needs to be exported from + * a shared library, but it might have other side effects. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DECLSPEC __attribute__ ((visibility("default"))) + +/** + * A macro to set a function's calling conventions. + * + * SDL uses this macro for all its public functions, and any callbacks it + * defines. This macro guarantees that calling conventions match between SDL + * and the app, even if the two were built with different compilers or + * optimization settings. + * + * When writing a callback function, it is very important for it to be + * correctly tagged with SDLCALL, as mismatched calling conventions can cause + * strange behaviors and can be difficult to diagnose. Plus, on many + * platforms, SDLCALL is defined to nothing, so compilers won't be able to + * warn that the tag is missing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDLCALL __cdecl + +/** + * A macro to request a function be inlined. + * + * This is a hint to the compiler to inline a function. The compiler is free + * to ignore this request. On compilers without inline support, this is + * defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INLINE __inline + +/** + * A macro to demand a function be inlined. + * + * This is a command to the compiler to inline a function. SDL uses this macro + * in its public headers for a handful of simple functions. On compilers + * without forceinline support, this is defined to `static SDL_INLINE`, which + * is often good enough. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FORCE_INLINE __forceinline + +/** + * A macro to tag a function as never-returning. + * + * This is a hint to the compiler that a function does not return. An example + * of a function like this is the C runtime's exit() function. + * + * This hint can lead to code optimizations, and help analyzers understand + * code flow better. On compilers without noreturn support, this is defined to + * nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NORETURN __attribute__((noreturn)) + +/** + * A macro to tag a function as never-returning (for analysis purposes). + * + * This is almost identical to SDL_NORETURN, except functions marked with this + * _can_ actually return. The difference is that this isn't used for code + * generation, but rather static analyzers use this information to assume + * truths about program state and available code paths. Specifically, this tag + * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this + * tag behind the scenes. Generally, apps that don't understand the specific + * use-case for this tag should avoid using it directly. + * + * On compilers without analyzer_noreturn support, this is defined to nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) + + +/** + * A macro to signal that a case statement without a `break` is intentional. + * + * C compilers have gotten more aggressive about warning when a switch's + * `case` block does not end with a `break` or other flow control statement, + * flowing into the next case's code, as this is a common accident that leads + * to strange bugs. But sometimes falling through to the next case is the + * correct and desired behavior. This symbol lets an app communicate this + * intention to the compiler, so it doesn't generate a warning. + * + * It is used like this: + * + * ```c + * switch (x) { + * case 1: + * DoSomethingOnlyForOne(); + * SDL_FALLTHROUGH; // tell the compiler this was intentional. + * case 2: + * DoSomethingForOneAndTwo(); + * break; + * } + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FALLTHROUGH [[fallthrough]] + +/** + * A macro to tag a function's return value as critical. + * + * This is a hint to the compiler that a function's return value should not be + * ignored. + * + * If an NODISCARD function's return value is thrown away (the function is + * called as if it returns `void`), the compiler will issue a warning. + * + * While it's generally good practice to check return values for errors, often + * times legitimate programs do not for good reasons. Be careful about what + * functions are tagged as NODISCARD. It operates best when used on a function + * that's failure is surprising and catastrophic; a good example would be a + * program that checks the return values of all its file write function calls + * but not the call to close the file, which it assumes incorrectly never + * fails. + * + * Function callers that want to throw away a NODISCARD return value can call + * the function with a `(void)` cast, which informs the compiler the act is + * intentional. + * + * On compilers without nodiscard support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NODISCARD [[nodiscard]] + +/** + * A macro to tag a function as an allocator. + * + * This is a hint to the compiler that a function is an allocator, like + * malloc(), with certain rules. A description of how GCC treats this hint is + * here: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute + * + * On compilers without allocator tag support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) + +/** + * A macro to tag a function as returning a certain allocation. + * + * This is a hint to the compiler that a function allocates and returns a + * specific amount of memory based on one of its arguments. For example, the C + * runtime's malloc() function could use this macro with an argument of 1 + * (first argument to malloc is the size of the allocation). + * + * On compilers without alloc_size support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) + +/** + * A macro to tag a pointer variable, to help with pointer aliasing. + * + * A good explanation of the restrict keyword is here: + * + * https://en.wikipedia.org/wiki/Restrict + * + * On compilers without restrict support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_RESTRICT __restrict__ + +/** + * Check if the compiler supports a given builtin functionality. + * + * This allows preprocessor checks for things that otherwise might fail to + * compile. + * + * Supported by virtually all clang versions and more-recent GCCs. Use this + * instead of checking the clang version if possible. + * + * On compilers without has_builtin support, this is defined to 0 (always + * false). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAS_BUILTIN(x) __has_builtin(x) + +/* end of wiki documentation section. */ +#endif + +#ifndef SDL_HAS_BUILTIN +#ifdef __has_builtin +#define SDL_HAS_BUILTIN(x) __has_builtin(x) +#else +#define SDL_HAS_BUILTIN(x) 0 +#endif +#endif + #ifndef SDL_DEPRECATED # if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ # define SDL_DEPRECATED __attribute__((deprecated)) @@ -53,7 +312,7 @@ /* Some compilers use a special export keyword */ #ifndef SDL_DECLSPEC -# if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_CYGWIN) || defined(SDL_PLATFORM_GDK) +# if defined(SDL_PLATFORM_WINDOWS) # ifdef DLL_EXPORT # define SDL_DECLSPEC __declspec(dllexport) # else @@ -70,7 +329,7 @@ /* By default SDL uses the C calling convention */ #ifndef SDLCALL -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_GDK)) && !defined(__GNUC__) +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) #define SDLCALL __cdecl #else #define SDLCALL diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_bits.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_bits.h index 72be082..7435ce6 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_bits.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_bits.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -36,10 +36,6 @@ extern "C" { #endif -/** - * \file SDL_bits.h - */ - #if defined(__WATCOMC__) && defined(__386__) extern __inline int _SDL_bsr_watcom(Uint32); #pragma aux _SDL_bsr_watcom = \ @@ -65,7 +61,7 @@ extern __inline int _SDL_bsr_watcom(Uint32); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { @@ -82,10 +78,10 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) return -1; } return _SDL_bsr_watcom(x); -#elif defined(_MSC_VER) +#elif defined(_MSC_VER) && _MSC_VER >= 1400 unsigned long index; if (_BitScanReverse(&index, x)) { - return index; + return (int)index; } return -1; #else @@ -120,8 +116,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * Determine if a unsigned 32-bit value has exactly one bit set. * * If there are no bits set (`x` is zero), or more than one bit set, this - * returns SDL_FALSE. If any one bit is exclusively set, this returns - * SDL_TRUE. + * returns false. If any one bit is exclusively set, this returns true. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is @@ -129,18 +124,18 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine. - * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. + * \returns true if exactly one bit is set in `x`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_HasExactlyOneBitSet32(Uint32 x) +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_blendmode.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_blendmode.h index 76aa197..8f00cbc 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_blendmode.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_blendmode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,7 @@ * * Blend modes decide how two colors will mix together. There are both * standard modes for basic needs and a means to create custom modes, - * dictating what sort of math to do what on what color components. + * dictating what sort of math to do on what color components. */ #ifndef SDL_blendmode_h_ @@ -45,7 +45,7 @@ extern "C" { * * Additional values may be obtained from SDL_ComposeCustomBlendMode. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_ComposeCustomBlendMode */ @@ -64,7 +64,7 @@ typedef Uint32 SDL_BlendMode; * The blend operation used when combining source and destination pixel * components. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendOperation { @@ -83,7 +83,7 @@ typedef enum SDL_BlendOperation * operation. The comma-separated factors listed above are always applied in * the component order red, green, blue, and alpha. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendFactor { @@ -177,7 +177,9 @@ typedef enum SDL_BlendFactor * \returns an SDL_BlendMode that represents the chosen factors and * operations. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode * \sa SDL_GetRenderDrawBlendMode diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_camera.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_camera.h index 3d4c57e..c4d0596 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_camera.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_camera.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -28,13 +28,51 @@ * devices can be enumerated, queried, and opened. Once opened, it will * provide SDL_Surface objects as new frames of video come in. These surfaces * can be uploaded to an SDL_Texture or processed as pixels in memory. + * + * Several platforms will alert the user if an app tries to access a camera, + * and some will present a UI asking the user if your application should be + * allowed to obtain images at all, which they can deny. A successfully opened + * camera will not provide images until permission is granted. Applications, + * after opening a camera device, can see if they were granted access by + * either polling with the SDL_GetCameraPermissionState() function, or waiting + * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED + * event. Platforms that don't have any user approval process will report + * approval immediately. + * + * Note that SDL cameras only provide video as individual frames; they will + * not provide full-motion video encoded in a movie file format, although an + * app is free to encode the acquired frames into any format it likes. It also + * does not provide audio from the camera hardware through this API; not only + * do many webcams not have microphones at all, many people--from streamers to + * people on Zoom calls--will want to use a separate microphone regardless of + * the camera. In any case, recorded audio will be available through SDL's + * audio API no matter what hardware provides the microphone. + * + * ## Camera gotchas + * + * Consumer-level camera hardware tends to take a little while to warm up, + * once the device has been opened. Generally most camera apps have some sort + * of UI to take a picture (a button to snap a pic while a preview is showing, + * some sort of multi-second countdown for the user to pose, like a photo + * booth), which puts control in the users' hands, or they are intended to + * stay on for long times (Pokemon Go, etc). + * + * It's not uncommon that a newly-opened camera will provide a couple of + * completely black frames, maybe followed by some under-exposed images. If + * taking a single frame automatically, or recording video from a camera's + * input without the user initiating it from a preview, it could be wise to + * drop the first several frames (if not the first several _seconds_ worth of + * frames!) before using images from a camera. */ #ifndef SDL_camera_h_ #define SDL_camera_h_ +#include #include -#include +#include +#include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -50,7 +88,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -59,7 +97,7 @@ typedef Uint32 SDL_CameraID; /** * The opaque structure used to identify an opened SDL camera. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Camera SDL_Camera; @@ -69,7 +107,7 @@ typedef struct SDL_Camera SDL_Camera; * Cameras often support multiple formats; each one will be encapsulated in * this struct. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetCameraSupportedFormats * \sa SDL_GetCameraFormat @@ -87,7 +125,7 @@ typedef struct SDL_CameraSpec /** * The position of camera in relation to system device. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCameraPosition */ @@ -116,7 +154,7 @@ typedef enum SDL_CameraPosition * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameraDriver */ @@ -140,7 +178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumCameraDrivers */ @@ -158,7 +196,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); @@ -173,7 +211,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -211,7 +249,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_OpenCamera @@ -227,7 +265,7 @@ extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -246,7 +284,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -265,7 +303,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * You can call SDL_GetCameraFormat() to get the actual data format if passing * a NULL spec here. You can see the exact specs a device can support without - * conversion with SDL_GetCameraSupportedSpecs(). + * conversion with SDL_GetCameraSupportedFormats(). * * SDL will not attempt to emulate framerate; it will try to set the hardware * to the rate closest to the requested speed, but it won't attempt to limit @@ -278,10 +316,11 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * the camera, and they can choose Yes or No at that point. Until they do, the * camera will not be usable. The app should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On - * platforms that don't require explicit user approval (and perhaps in places - * where the user previously permitted access), the approval event might come - * immediately, but it might come seconds, minutes, or hours later! + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. On platforms that don't require explicit user approval (and + * perhaps in places where the user previously permitted access), the approval + * event might come immediately, but it might come seconds, minutes, or hours + * later! * * \param instance_id the camera device instance ID. * \param spec the desired format for data the device will provide. Can be @@ -291,7 +330,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_GetCameraFormat @@ -324,7 +363,7 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera * \sa SDL_CloseCamera @@ -340,7 +379,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -355,7 +394,7 @@ extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera); @@ -366,23 +405,24 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * be converting to this format behind the scenes. * * If the system is waiting for the user to approve access to the camera, as - * some platforms require, this will return SDL_FALSE, but this isn't - * necessarily a fatal error; you should either wait for an + * some platforms require, this will return false, but this isn't necessarily + * a fatal error; you should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. * * \param camera opened camera device. * \param spec the SDL_CameraSpec to be initialized by this function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); /** * Acquire a frame. @@ -404,14 +444,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * After use, the frame should be released with SDL_ReleaseCameraFrame(). If * you don't do this, the system may stop providing more video! * - * Do not call SDL_FreeSurface() on the returned surface! It must be given + * Do not call SDL_DestroySurface() on the returned surface! It must be given * back to the camera subsystem with SDL_ReleaseCameraFrame! * * If the system is waiting for the user to approve access to the camera, as * some platforms require, this will return NULL (no frames available); you * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or - * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() - * occasionally until it returns non-zero. + * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll + * SDL_GetCameraPermissionState() occasionally until it returns non-zero. * * \param camera opened camera device. * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on @@ -421,7 +461,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReleaseCameraFrame */ @@ -449,7 +489,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireCameraFrame */ @@ -464,9 +504,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_ * \threadsafety It is safe to call this function from any thread, but no * thread may reference `device` once this function is called. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_OpenCameraWithSpec * \sa SDL_OpenCamera */ extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_clipboard.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_clipboard.h index 4d4ae32..0d3cbb4 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_clipboard.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_clipboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,51 @@ * from other processes and publishing information of its own. * * This is not just text! SDL apps can access and publish data by mimetype. + * + * ## Basic use (text) + * + * Obtaining and publishing simple text to the system clipboard is as easy as + * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively. + * These deal with C strings in UTF-8 encoding. Data transmission and encoding + * conversion is completely managed by SDL. + * + * ## Clipboard callbacks (data other than text) + * + * Things get more complicated when the clipboard contains something other + * than text. Not only can the system clipboard contain data of any type, in + * some cases it can contain the same data in different formats! For example, + * an image painting app might let the user copy a graphic to the clipboard, + * and offers it in .BMP, .JPG, or .PNG format for other apps to consume. + * + * Obtaining clipboard data ("pasting") like this is a matter of calling + * SDL_GetClipboardData() and telling it the mimetype of the data you want. + * But how does one know if that format is available? SDL_HasClipboardData() + * can report if a specific mimetype is offered, and + * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes + * available, so the app can decide what to do with the data and what formats + * it can support. + * + * Setting the clipboard ("copying") to arbitrary data is done with + * SDL_SetClipboardData. The app does not provide the data in this call, but + * rather the mimetypes it is willing to provide and a callback function. + * During the callback, the app will generate the data. This allows massive + * data sets to be provided to the clipboard, without any data being copied + * before it is explicitly requested. More specifically, it allows an app to + * offer data in multiple formats without providing a copy of all of them + * upfront. If the app has an image that it could provide in PNG or JPG + * format, it doesn't have to encode it to either of those unless and until + * something tries to paste it. + * + * ## Primary Selection + * + * The X11 and Wayland video targets have a concept of the "primary selection" + * in addition to the usual clipboard. This is generally highlighted (but not + * explicitly copied) text from various apps. SDL offers APIs for this through + * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers + * these APIs on platforms without this concept, too, but only so far that it + * will keep a copy of a string that the app sets for later retrieval; the + * operating system will not ever attempt to change the string externally if + * it doesn't support a primary selection. */ #ifndef SDL_clipboard_h_ @@ -46,27 +91,31 @@ extern "C" { * Put UTF-8 text into the clipboard. * * \param text the text to store in the clipboard. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_HasClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); /** * Get UTF-8 text from the clipboard. * - * This functions returns empty string if there was not enough memory left for - * a copy of the clipboard's content. + * This functions returns an empty string if there was 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 * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardText * \sa SDL_SetClipboardText @@ -76,40 +125,46 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); /** * Query whether the clipboard exists and contains a non-empty text string. * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * \returns true if the clipboard has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_SetClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * * \param text the text to store in the primary selection. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_HasPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPrimarySelectionText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); /** * Get UTF-8 text from the primary selection. * - * This functions returns empty string if there was not enough memory left for - * a copy of the primary selection's content. + * This functions returns an empty string if there was 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 * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasPrimarySelectionText * \sa SDL_SetPrimarySelectionText @@ -120,15 +175,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * Query whether the primary selection exists and contains a non-empty text * string. * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. + * \returns true if the primary selection has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_SetPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); /** * Callback function that will be called when data for the specified mime-type @@ -148,7 +204,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); * breakage in receiving applications. 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.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -160,7 +216,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c * * \param userdata a pointer to provided user data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -170,13 +226,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * Offer clipboard data to the OS. * * Tell the operating system that the application is offering clipboard data - * for each of the proivded mime-types. Once another application requests the - * data the callback function will be called allowing it to generate and + * for each of the provided mime-types. Once another application requests the + * data the callback function will be called, allowing it to generate and * 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 - * document) + * document). * * \param callback a function pointer to the function that provides the * clipboard data. @@ -185,28 +241,32 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \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 num_mime_types the number of mime-types in the mime_types list. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearClipboardData * \sa SDL_GetClipboardData * \sa SDL_HasClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** * Clear the clipboard data. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); /** * Get the data from clipboard for a given mime type. @@ -220,7 +280,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); * for more information. This should be freed with SDL_free() when it * is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardData * \sa SDL_SetClipboardData @@ -231,15 +293,34 @@ 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 SDL_TRUE if there exists data in clipboard for the provided mime - * type, SDL_FALSE if it does not. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData * \sa SDL_GetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \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 + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_close_code.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_close_code.h index fa4d3d1..da1dea7 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_close_code.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_close_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -21,7 +21,10 @@ /* * This file reverses the effects of SDL_begin_code.h and should be included - * after you finish any function and structure declarations in your headers + * after you finish any function and structure declarations in your headers. + * + * SDL's headers use this; applications generally should not include this + * header directly. */ #ifndef SDL_begin_code_h diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_copying.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_copying.h index dcbdcea..747bd35 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_copying.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_copying.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_cpuinfo.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_cpuinfo.h index e7ced26..1745bd9 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_cpuinfo.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_cpuinfo.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,6 +29,12 @@ * These functions are largely concerned with reporting if the system has * access to various SIMD instruction sets, but also has other important info * to share, such as system RAM size and number of logical CPU cores. + * + * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are + * available on all platforms, even if they don't make sense (an ARM processor + * will never have SSE and an x86 processor will never have NEON, for example, + * but these functions still exist and will simply return false in these + * cases). */ #ifndef SDL_cpuinfo_h_ @@ -49,20 +55,22 @@ extern "C" { * processors have a 128 byte cache line. We use the larger value to be * generally safe. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CACHELINE_SIZE 128 /** - * Get the number of CPU cores available. + * Get the number of logical CPU cores available. * * \returns the total number of logical CPU cores. On CPUs that include * technologies such as hyperthreading, the number of logical cores * may be more than the number of physical cores. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); /** * Determine the L1 cache line size of the CPU. @@ -72,7 +80,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); * * \returns the L1 cache line size of the CPU, in bytes. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); @@ -82,144 +92,164 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * This always returns false on CPUs that aren't using PowerPC instruction * sets. * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. + * \returns true if the CPU has AltiVec features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); /** * Determine whether the CPU has MMX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. + * \returns true if the CPU has MMX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); /** * Determine whether the CPU has SSE features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. + * \returns true if the CPU has SSE features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); /** * Determine whether the CPU has SSE2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); /** * Determine whether the CPU has SSE3 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. + * \returns true if the CPU has SSE3 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); /** * Determine whether the CPU has SSE4.1 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.1 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); /** * Determine whether the CPU has SSE4.2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); /** * Determine whether the CPU has AVX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. + * \returns true if the CPU has AVX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX2 * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); /** * Determine whether the CPU has AVX2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. + * \returns true if the CPU has AVX2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); /** * Determine whether the CPU has AVX-512F (foundation) features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. + * \returns true if the CPU has AVX-512F features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX2 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); /** * Determine whether the CPU has ARM SIMD (ARMv6) features. @@ -228,24 +258,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. + * \returns true if the CPU has ARM SIMD features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasNEON */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); /** * Determine whether the CPU has NEON (ARM SIMD) features. * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. + * \returns true if the CPU has ARM NEON features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); /** * Determine whether the CPU has LSX (LOONGARCH SIMD) features. @@ -253,12 +287,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LSX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); /** * Determine whether the CPU has LASX (LOONGARCH SIMD) features. @@ -266,19 +301,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LASX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); /** * Get the amount of RAM configured in the system. * * \returns the amount of RAM configured in the system in MiB. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); @@ -297,7 +335,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); * \returns the alignment in bytes needed for available, known SIMD * instructions. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc * \sa SDL_aligned_free diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_dialog.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_dialog.h index 8a198a8..460038f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_dialog.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_dialog.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,12 +23,23 @@ * # CategoryDialog * * File dialog support. + * + * SDL offers file dialogs, to let users select files with native GUI + * interfaces. There are "open" dialogs, "save" dialogs, and folder selection + * dialogs. The app can control some details, such as filtering to specific + * files, or whether multiple files can be selected by the user. + * + * Note that launching a file dialog is a non-blocking operation; control + * returns to the app immediately, and a callback is called later (possibly in + * another thread) when the user makes a choice. */ #ifndef SDL_dialog_h_ #define SDL_dialog_h_ +#include #include +#include #include #include @@ -48,12 +59,13 @@ extern "C" { * hyphens, underscores and periods. Alternatively, the whole string can be a * single asterisk ("*"), which serves as an "All files" filter. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef struct SDL_DialogFileFilter { @@ -75,31 +87,34 @@ typedef struct SDL_DialogFileFilter * is a null-terminated list of pointers to C strings, each containing a * path. * - * The filelist argument does not need to be freed; it will automatically be - * freed when the callback returns. + * The filelist argument should not be freed; it will automatically be freed + * when the callback returns. * * The filter argument is the index of the filter that was selected, or -1 if * no filter was selected or if the platform or method doesn't support * fetching the selected filter. * + * In Android, the `filelist` are `content://` URIs. They should be opened + * using SDL_IOFromFile() with appropriate modes. This applies both to open + * and save file dialog. + * * \param userdata an app-provided pointer, for the callback's use. * \param filelist the file(s) chosen by the user. * \param filter index of the selected filter. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter); /** * Displays a dialog that lets the user select a file on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -117,47 +132,41 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); /** * Displays a dialog that lets the user choose a new or existing file on their * filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -174,44 +183,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); /** * Displays a dialog that lets the user select a folder on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -229,31 +232,105 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is always -1 for SDL_ShowOpenFolderDialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \param window the window that the dialog should be modal for, may be NULL. * Not all platforms support this option. - * \param default_location the default folder or file to start the dialog at. - * May be NULL. Not all platforms support this option. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); + +/** + * Various types of file dialogs. + * + * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of + * dialog to present to the user. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ShowFileDialogWithProperties + */ +typedef enum SDL_FileDialogType +{ + SDL_FILEDIALOG_OPENFILE, + SDL_FILEDIALOG_SAVEFILE, + SDL_FILEDIALOG_OPENFOLDER +} SDL_FileDialogType; + +/** + * Create and launch a file dialog with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of + * SDL_DialogFileFilter structs, which will be used as filters for + * file-based selections. Ignored if the dialog is an "Open Folder" dialog. + * If non-NULL, the array of filters must remain valid at least until the + * callback is invoked. + * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the + * array of filters, if it exists. + * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should + * be modal for. + * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to + * start the dialog at. + * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select + * more than one entry. + * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. + * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button + * should have. + * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button + * should have. + * + * Note that each platform may or may not support any of the properties. + * + * \param type the type of file dialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param props the properties to use. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FileDialogType + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); + +#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" +#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" +#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" +#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" +#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" +#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" +#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" +#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -261,4 +338,4 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback #endif #include -#endif /* SDL_joystick_h_ */ +#endif /* SDL_dialog_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_egl.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_egl.h index cc557d6..65d4e96 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_egl.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_egl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_endian.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_endian.h index cb3d7f3..a34e9d4 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_endian.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_endian.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,20 @@ /** * # CategoryEndian * - * Functions for reading and writing endian-specific values. + * Functions converting endian-specific values to different byte orders. + * + * These functions either unconditionally swap byte order (SDL_Swap16, + * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's + * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, + * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the + * latter case, the functionality is provided by macros that become no-ops if + * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE + * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC + * processor (bigendian), the macros behavior is reversed. + * + * The swap routines are inline functions, and attempt to use compiler + * intrinsics, inline assembly, and other magic to make byteswapping + * efficient. */ #ifndef SDL_endian_h_ @@ -51,12 +64,71 @@ _m_prefetch(void *__P) * \name The two types of endianness */ /* @{ */ + + +/** + * A value to represent littleendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_LIL_ENDIAN + * SDL_Log("This system is littleendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_BIG_ENDIAN + */ #define SDL_LIL_ENDIAN 1234 + +/** + * A value to represent bigendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_LIL_ENDIAN + */ #define SDL_BIG_ENDIAN 4321 + /* @} */ #ifndef SDL_BYTEORDER -#ifdef SDL_PLATFORM_LINUX +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's byte order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +#elif defined(SDL_PLATFORM_LINUX) #include #define SDL_BYTEORDER __BYTE_ORDER #elif defined(SDL_PLATFORM_SOLARIS) @@ -97,8 +169,29 @@ _m_prefetch(void *__P) #endif /* !SDL_BYTEORDER */ #ifndef SDL_FLOATWORDORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's floating point word order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN + * SDL_Log("This system's floats are bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN /* predefs from newer gcc versions: */ -#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) #if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) #define SDL_FLOATWORDORDER SDL_LIL_ENDIAN #elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) @@ -125,10 +218,6 @@ _m_prefetch(void *__P) extern "C" { #endif -/** - * \file SDL_endian.h - */ - /* various modern compilers may have builtin swap */ #if defined(__GNUC__) || defined(__clang__) # define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \ @@ -148,6 +237,7 @@ extern "C" { #endif /* Byte swap 16-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP16 #define SDL_Swap16(x) __builtin_bswap16(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -191,8 +281,10 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); } #endif +#endif /* Byte swap 32-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP32 #define SDL_Swap32(x) __builtin_bswap32(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -239,8 +331,10 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) ((x >> 8) & 0x0000FF00) | (x >> 24))); } #endif +#endif /* Byte swap 64-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP64 #define SDL_Swap64(x) __builtin_bswap64(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -290,7 +384,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) return (x); } #endif - +#endif /** * Byte-swap a floating point number. @@ -309,7 +403,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { @@ -348,7 +442,7 @@ SDL_FORCE_INLINE float SDL_SwapFloat(float x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } @@ -369,7 +463,7 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } @@ -390,7 +484,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } @@ -404,7 +498,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16LE(x) SwapOnlyIfNecessary(x) @@ -418,7 +514,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32LE(x) SwapOnlyIfNecessary(x) @@ -432,7 +530,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64LE(x) SwapOnlyIfNecessary(x) @@ -446,7 +546,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x) @@ -460,7 +562,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16BE(x) SwapOnlyIfNecessary(x) @@ -474,7 +578,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32BE(x) SwapOnlyIfNecessary(x) @@ -488,7 +594,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64BE(x) SwapOnlyIfNecessary(x) @@ -502,7 +610,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x) diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_error.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_error.h index a98823f..934967c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_error.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_error.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,26 @@ * # CategoryError * * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. */ #ifndef SDL_error_h_ @@ -44,8 +64,8 @@ extern "C" { * * Calling this function will replace any previous error message that was set. * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: * * ```c * if (error_code) { @@ -56,25 +76,49 @@ extern "C" { * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if * any. - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_GetError + * \sa SDL_SetErrorV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * \param fmt a printf()-style message format string. + * \param ap a variable argument list. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1); /** * Set an error indicating that memory allocation failed. * * This function does not do any memory allocation. * - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); /** * Retrieve a message about the last error that occurred on the current @@ -104,7 +148,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); * or an empty string if there hasn't been an error message set since * the last call to SDL_ClearError(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_SetError @@ -114,14 +160,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); /** * Clear any previous error message for this thread. * - * \returns SDL_TRUE. + * \returns true. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetError * \sa SDL_SetError */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); /** * \name Internal error functions @@ -130,8 +178,43 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); * Private error reporting function - used internally. */ /* @{ */ + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_Unsupported() SDL_SetError("That operation is not supported") + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * A common usage pattern inside SDL is this: + * + * ```c + * bool MyFunction(const char *str) { + * if (!str) { + * return SDL_InvalidParamError("str"); // returns false. + * } + * DoSomething(str); + * return true; + * } + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + /* @} *//* Internal error functions */ /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_events.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_events.h index fbe2bb0..1323e9f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_events.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_events.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,22 +23,50 @@ * # CategoryEvents * * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. */ #ifndef SDL_events_h_ #define SDL_events_h_ +#include #include +#include #include #include #include #include +#include #include #include -#include +#include +#include +#include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,29 +76,10 @@ extern "C" { /* General keyboard/mouse/pen state definitions */ -/** - * A value that signifies a button is no longer pressed. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_PRESSED - */ -#define SDL_RELEASED 0 - -/** - * A value that signifies a button has been pressed down. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_RELEASED - */ -#define SDL_PRESSED 1 - - /** * The types of events that can be delivered. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_EventType { @@ -148,7 +157,7 @@ typedef enum SDL_EventType SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */ SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */ SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled - in an event watcher, the window handle is still valid and can still be used to retrieve any userdata + in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid */ SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ @@ -203,6 +212,7 @@ typedef enum SDL_EventType SDL_EVENT_FINGER_DOWN = 0x700, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, + SDL_EVENT_FINGER_CANCELED, /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ @@ -243,6 +253,13 @@ typedef enum SDL_EventType /* Render events */ SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ + SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + SDL_EVENT_PRIVATE0 = 0x4000, + SDL_EVENT_PRIVATE1, + SDL_EVENT_PRIVATE2, + SDL_EVENT_PRIVATE3, /* Internal events */ SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ @@ -265,7 +282,7 @@ typedef enum SDL_EventType /** * Fields shared by every event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CommonEvent { @@ -277,7 +294,7 @@ typedef struct SDL_CommonEvent /** * Display state change event data (event.display.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DisplayEvent { @@ -292,7 +309,7 @@ typedef struct SDL_DisplayEvent /** * Window state change event data (event.window.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_WindowEvent { @@ -307,7 +324,7 @@ typedef struct SDL_WindowEvent /** * Keyboard device event structure (event.kdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_KeyboardDeviceEvent { @@ -326,7 +343,7 @@ typedef struct SDL_KeyboardDeviceEvent * event scancode and modifiers directly from the keyboard layout, bypassing * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_HINT_KEYCODE_OPTIONS @@ -342,8 +359,8 @@ typedef struct SDL_KeyboardEvent SDL_Keycode key; /**< SDL virtual key code */ SDL_Keymod mod; /**< current key modifiers */ Uint16 raw; /**< The platform dependent scancode for this event */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ } SDL_KeyboardEvent; /** @@ -353,7 +370,7 @@ typedef struct SDL_KeyboardEvent * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingEvent { @@ -369,7 +386,7 @@ typedef struct SDL_TextEditingEvent /** * Keyboard IME candidates event structure (event.edit_candidates.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingCandidatesEvent { @@ -380,7 +397,10 @@ typedef struct SDL_TextEditingCandidatesEvent const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ Sint32 num_candidates; /**< The number of strings in `candidates` */ Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ - SDL_bool horizontal; /**< SDL_TRUE if the list is horizontal, SDL_FALSE if it's vertical */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_TextEditingCandidatesEvent; /** @@ -389,7 +409,7 @@ typedef struct SDL_TextEditingCandidatesEvent * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput @@ -406,7 +426,7 @@ typedef struct SDL_TextInputEvent /** * Mouse device event structure (event.mdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseDeviceEvent { @@ -419,7 +439,7 @@ typedef struct SDL_MouseDeviceEvent /** * Mouse motion event structure (event.motion.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseMotionEvent { @@ -427,7 +447,7 @@ typedef struct SDL_MouseMotionEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id or SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ SDL_MouseButtonFlags state; /**< The current button state */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ @@ -438,7 +458,7 @@ typedef struct SDL_MouseMotionEvent /** * Mouse button event structure (event.button.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseButtonEvent { @@ -446,9 +466,9 @@ typedef struct SDL_MouseButtonEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding; float x; /**< X coordinate, relative to window */ @@ -458,7 +478,7 @@ typedef struct SDL_MouseButtonEvent /** * Mouse wheel event structure (event.wheel.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseWheelEvent { @@ -466,7 +486,7 @@ typedef struct SDL_MouseWheelEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */ float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ @@ -477,7 +497,7 @@ typedef struct SDL_MouseWheelEvent /** * Joystick axis motion event structure (event.jaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyAxisEvent { @@ -496,7 +516,7 @@ typedef struct SDL_JoyAxisEvent /** * Joystick trackball motion event structure (event.jball.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBallEvent { @@ -515,7 +535,7 @@ typedef struct SDL_JoyBallEvent /** * Joystick hat position change event structure (event.jhat.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyHatEvent { @@ -538,7 +558,7 @@ typedef struct SDL_JoyHatEvent /** * Joystick button event structure (event.jbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyButtonEvent { @@ -547,7 +567,7 @@ typedef struct SDL_JoyButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; @@ -555,7 +575,12 @@ typedef struct SDL_JoyButtonEvent /** * Joystick device event structure (event.jdevice.*) * - * \since This struct is available since SDL 3.0.0. + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GamepadDeviceEvent */ typedef struct SDL_JoyDeviceEvent { @@ -566,9 +591,9 @@ typedef struct SDL_JoyDeviceEvent } SDL_JoyDeviceEvent; /** - * Joysick battery level change event structure (event.jbattery.*) + * Joystick battery level change event structure (event.jbattery.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBatteryEvent { @@ -583,7 +608,7 @@ typedef struct SDL_JoyBatteryEvent /** * Gamepad axis motion event structure (event.gaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadAxisEvent { @@ -603,7 +628,7 @@ typedef struct SDL_GamepadAxisEvent /** * Gamepad button event structure (event.gbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadButtonEvent { @@ -612,7 +637,7 @@ typedef struct SDL_GamepadButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_GamepadButtonEvent; @@ -621,7 +646,16 @@ typedef struct SDL_GamepadButtonEvent /** * Gamepad device event structure (event.gdevice.*) * - * \since This struct is available since SDL 3.0.0. + * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent + * and an SDL_GamepadDeviceEvent. + * + * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged + * in during SDL_Init() and are recognized as gamepads. It will also send + * events for joysticks that get gamepad mappings at runtime. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_JoyDeviceEvent */ typedef struct SDL_GamepadDeviceEvent { @@ -634,7 +668,7 @@ typedef struct SDL_GamepadDeviceEvent /** * Gamepad touchpad event structure (event.gtouchpad.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadTouchpadEvent { @@ -652,7 +686,7 @@ typedef struct SDL_GamepadTouchpadEvent /** * Gamepad sensor event structure (event.gsensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadSensorEvent { @@ -668,7 +702,7 @@ typedef struct SDL_GamepadSensorEvent /** * Audio device event structure (event.adevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AudioDeviceEvent { @@ -676,7 +710,7 @@ typedef struct SDL_AudioDeviceEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ - Uint8 recording; /**< zero if a playback device, non-zero if a recording device. */ + bool recording; /**< false if a playback device, true if a recording device. */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -685,7 +719,7 @@ typedef struct SDL_AudioDeviceEvent /** * Camera device event structure (event.cdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CameraDeviceEvent { @@ -695,14 +729,43 @@ typedef struct SDL_CameraDeviceEvent SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ } SDL_CameraDeviceEvent; + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RenderEvent +{ + SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window containing the renderer in question. */ +} SDL_RenderEvent; + + /** * Touch finger event structure (event.tfinger.*) * - * \since This struct is available since SDL 3.0.0. + * Coordinates in this event are normalized. `x` and `y` are normalized to a + * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top + * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are + * normalized in the ranges of -1.0f (traversed all the way from the bottom or + * right to all the way up or left) to 1.0f (traversed all the way from the + * top or left to all the way down or right). + * + * Note that while the coordinates are _normalized_, they are not _clamped_, + * which means in some circumstances you can get a value outside of this + * range. For example, a renderer using logical presentation might give a + * negative value when the touch is in the letterboxing. Some platforms might + * report a touch outside of the window, which will also be outside of the + * range. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TouchFingerEvent { - SDL_EventType type; /**< SDL_EVENT_FINGER_MOTION or SDL_EVENT_FINGER_DOWN or SDL_EVENT_FINGER_UP */ + SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_TouchID touchID; /**< The touch device id */ @@ -728,14 +791,14 @@ typedef struct SDL_TouchFingerEvent * is there." The pen touching and lifting off from the tablet while not * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenProximityEvent { SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ } SDL_PenProximityEvent; @@ -748,18 +811,18 @@ typedef struct SDL_PenProximityEvent * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when * dealing with pen motion. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenMotionEvent { SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ } SDL_PenMotionEvent; /** @@ -768,7 +831,7 @@ typedef struct SDL_PenMotionEvent * These events come when a pen touches a surface (a tablet, etc), or lifts * off from one. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenTouchEvent { @@ -778,10 +841,10 @@ typedef struct SDL_PenTouchEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ - Uint8 eraser; /**< Non-zero if eraser end is used (not all pens support this). */ - Uint8 state; /**< SDL_PRESSED (pen is touching) or SDL_RELEASED (pen is lifted off) */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ } SDL_PenTouchEvent; /** @@ -790,7 +853,7 @@ typedef struct SDL_PenTouchEvent * This is for buttons on the pen itself that the user might click. The pen * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenButtonEvent { @@ -800,10 +863,10 @@ typedef struct SDL_PenButtonEvent SDL_WindowID windowID; /**< The window with mouse focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ Uint8 button; /**< The pen button index (first button is 1). */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ } SDL_PenButtonEvent; /** @@ -812,7 +875,7 @@ typedef struct SDL_PenButtonEvent * You might get some of these events even if the pen isn't touching the * tablet. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenAxisEvent { @@ -822,8 +885,8 @@ typedef struct SDL_PenAxisEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ SDL_PenAxis axis; /**< Axis that has changed */ float value; /**< New value of axis */ } SDL_PenAxisEvent; @@ -832,7 +895,7 @@ typedef struct SDL_PenAxisEvent * An event used to drop text or request a file open by the system * (event.drop.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DropEvent { @@ -850,19 +913,22 @@ typedef struct SDL_DropEvent * An event triggered when the clipboard contents have changed * (event.clipboard.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_ClipboardEvent { SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + bool owner; /**< are we owning the clipboard (internal update) */ + Sint32 num_mime_types; /**< number of mime types */ + const char **mime_types; /**< current mime types */ } SDL_ClipboardEvent; /** * Sensor event structure (event.sensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_SensorEvent { @@ -877,7 +943,7 @@ typedef struct SDL_SensorEvent /** * The "quit requested" event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_QuitEvent { @@ -895,7 +961,7 @@ typedef struct SDL_QuitEvent * the programmer; the only requirement is that '''type''' is a value obtained * from SDL_RegisterEvents(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_UserEvent { @@ -912,7 +978,10 @@ typedef struct SDL_UserEvent /** * The structure for all events in SDL. * - * \since This struct is available since SDL 3.0.0. + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. + * + * \since This struct is available since SDL 3.2.0. */ typedef union SDL_Event { @@ -951,6 +1020,7 @@ typedef union SDL_Event SDL_PenMotionEvent pmotion; /**< Pen motion event data */ SDL_PenButtonEvent pbutton; /**< Pen button event data */ SDL_PenAxisEvent paxis; /**< Pen axis event data */ + SDL_RenderEvent render; /**< Render event data */ SDL_DropEvent drop; /**< Drag and drop event data */ SDL_ClipboardEvent clipboard; /**< Clipboard event data */ @@ -981,10 +1051,6 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * * This function updates the event queue and internal input device state. * - * **WARNING**: This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider only doing those - * things on the main thread in any case. - * * SDL_PumpEvents() gathers all the pending input information from devices and * places it in the event queue. Without calls to SDL_PumpEvents() no events * would ever be placed on the queue. Often the need for calls to @@ -993,7 +1059,9 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * polling or waiting for events (e.g. you are filtering them), then you must * call SDL_PumpEvents() to force an event queue update. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent @@ -1001,11 +1069,17 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_EventAction { - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ } SDL_EventAction; /** @@ -1017,7 +1091,9 @@ typedef enum SDL_EventAction * event queue. * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. + * caller and will _not_ be removed from the queue. If you pass NULL for + * `events`, then `numevents` is ignored and the total number of matching + * events will be returned. * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the * caller and will be removed from the queue. @@ -1026,8 +1102,6 @@ typedef enum SDL_EventAction * Otherwise, the events may not be ready to be filtered when you call * SDL_PeepEvents(). * - * This function is thread-safe. - * * \param events destination buffer for the retrieved events, may be NULL to * leave the events in the queue and return the number of events * that would have been stored. @@ -1042,7 +1116,9 @@ typedef enum SDL_EventAction * \returns the number of events actually stored or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PumpEvents @@ -1058,14 +1134,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, * instead. * * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); /** @@ -1077,14 +1155,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); /** * Clear events of a specific type from the event queue. @@ -1106,7 +1186,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp * * \param type the type of event to be cleared; see SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvents */ @@ -1131,7 +1213,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * \param maxType the high end of event type to be cleared, inclusive; see * SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvent */ @@ -1171,16 +1255,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * * \param event the SDL_Event structure to be filled with the next event from * the queue, or NULL. - * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none - * available. + * \returns true if this got an event or false if there are none available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent * \sa SDL_WaitEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); /** * Wait indefinitely for the next available event. @@ -1193,16 +1278,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * * \param event the SDL_Event structure to be filled in with the next event * from the queue, or NULL. - * \returns SDL_TRUE on success or SDL_FALSE if there was an error while - * waiting for events; call SDL_GetError() for more information. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); /** * Wait until the specified timeout (in milliseconds) for the next available @@ -1221,16 +1308,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * from the queue, or NULL. * \param timeoutMS the maximum number of milliseconds to wait for the next * available event. - * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed - * without any events available. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEvent */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); /** * Add an event to the event queue. @@ -1244,8 +1333,6 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * Note: Pushing device input events onto the queue doesn't modify the state * of the device within SDL. * - * This function is thread-safe, and can be called from other threads safely. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter but events added with SDL_PeepEvents() do not. * @@ -1254,17 +1341,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * its own custom event types. * * \param event the SDL_Event to be added to the queue. - * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on - * failure; call SDL_GetError() for more information. A common reason - * for error is the event queue being full. + * \returns true on success, false if the event was filtered or on failure; + * call SDL_GetError() for more information. A common reason for + * error is the event queue being full. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PeepEvents * \sa SDL_PollEvent * \sa SDL_RegisterEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); /** * A function pointer used for callbacks that watch the event queue. @@ -1272,29 +1361,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * SDL_AddEventWatch, etc. * \param event the event that triggered the callback. - * \returns SDL_TRUE to permit event to be added to the queue, and SDL_FALSE - * to disallow it. When used with SDL_AddEventWatch, the return value - * is ignored. + * \returns true to permit event to be added to the queue, and false to + * disallow it. When used with SDL_AddEventWatch, the return value is + * ignored. * * \threadsafety SDL may call this callback at any time from any thread; the * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetEventFilter * \sa SDL_AddEventWatch */ -typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. * - * If the filter function returns SDL_TRUE when called, then the event will be - * added to the internal queue. If it returns SDL_FALSE, then the event will - * be dropped from the queue, but the internal state will still be updated. - * This allows selective filtering of dynamically arriving events. + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. + * + * If the filter function returns true when called, then the event will be + * added to the internal queue. If it returns false, then the event will be + * dropped from the queue, but the internal state will still be updated. This + * allows selective filtering of dynamically arriving events. * * **WARNING**: Be very careful of what you do in the event filter function, * as it may run in a different thread! @@ -1303,17 +1395,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. @@ -1321,11 +1405,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \threadsafety SDL may call the filter callback at any time from any thread; - * the application is responsible for locking resources the - * callback touches that need to be protected. + * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch * \sa SDL_SetEventEnabled @@ -1344,13 +1426,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void * \param filter the current callback function will be stored here. * \param userdata the pointer that is passed to the current event filter will * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. + * \returns true on success or false if there is no event filter set. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); /** * Add a callback to be triggered when an event is added to the event queue. @@ -1372,17 +1456,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, * * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); /** * Remove an event watch callback added with SDL_AddEventWatch(). @@ -1393,7 +1477,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, v * \param filter the function originally passed to SDL_AddEventWatch(). * \param userdata the pointer originally passed to SDL_AddEventWatch(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -1401,7 +1487,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo /** * Run a specific filter function on the current event queue, removing any - * events for which the filter returns SDL_FALSE. + * events for which the filter returns false. * * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), * this function does not change the filter permanently, it only uses the @@ -1410,7 +1496,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo * \param filter the SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetEventFilter * \sa SDL_SetEventFilter @@ -1423,23 +1511,27 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void * * \param type the type of event; see SDL_EventType for details. * \param enabled whether to process the event or not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EventEnabled */ -extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); /** * Query the state of processing events by type. * * \param type the type of event; see SDL_EventType for details. - * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. + * \returns true if the event is being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); /** * Allocate a set of user-defined events, and return the beginning event @@ -1449,7 +1541,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); * \returns the beginning event number, or 0 if numevents is invalid or if * there are not enough user-defined events left. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent */ @@ -1461,7 +1555,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); * \param event an event containing a `windowID`. * \returns the associated window on success or NULL if there is none. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_filesystem.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_filesystem.h index 5faa244..af3ca27 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_filesystem.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_filesystem.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,23 @@ /** * # CategoryFilesystem * - * SDL Filesystem API. + * SDL offers an API for examining and manipulating the system's filesystem. + * This covers most things one would need to do with directories, except for + * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) + * and [CategoryAsyncIO](CategoryAsyncIO) instead). + * + * There are functions to answer necessary path questions: + * + * - Where is my app's data? SDL_GetBasePath(). + * - Where can I safely write files? SDL_GetPrefPath(). + * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder(). + * - What is this thing at this location? SDL_GetPathInfo(). + * - What items live in this folder? SDL_EnumerateDirectory(). + * - What items live in this folder by wildcard? SDL_GlobDirectory(). + * - What is my current working directory? SDL_GetCurrentDirectory(). + * + * SDL also offers functions to manipulate the directory tree: renaming, + * removing, copying files. */ #ifndef SDL_filesystem_h_ @@ -73,7 +89,7 @@ extern "C" { * doesn't implement this functionality, call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrefPath */ @@ -128,7 +144,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); * etc.). This should be freed with SDL_free() when it is no longer * needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBasePath */ @@ -143,66 +159,40 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * * * The folders supported per platform are: * - * | | Windows | WinRT/UWP |macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | - * | ----------- | ------- | --------- |--------- | ---- | ---------- | ----- | ---------- | - * | HOME | X | X | X | | X | X | X | - * | DESKTOP | X | X | X | | X | X | | - * | DOCUMENTS | X | X | X | | X | | | - * | DOWNLOADS | Vista+ | X | X | | X | | | - * | MUSIC | X | X | X | | X | | | - * | PICTURES | X | X | X | | X | | | - * | PUBLICSHARE | | | X | | X | | | - * | SAVEDGAMES | Vista+ | | | | | | | - * | SCREENSHOTS | Vista+ | X | | | | | | - * | TEMPLATES | X | X | X | | X | | | - * | VIDEOS | X | X | X* | | X | | | + * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | + * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- | + * | HOME | X | X | | X | X | X | + * | DESKTOP | X | X | | X | X | | + * | DOCUMENTS | X | X | | X | | | + * | DOWNLOADS | Vista+ | X | | X | | | + * | MUSIC | X | X | | X | | | + * | PICTURES | X | X | | X | | | + * | PUBLICSHARE | | X | | X | | | + * | SAVEDGAMES | Vista+ | | | | | | + * | SCREENSHOTS | Vista+ | | | | | | + * | TEMPLATES | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | * * Note that on macOS/iOS, the Videos folder is called "Movies". * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetUserFolder */ typedef enum SDL_Folder { - /** The folder which contains all of the current user's data, preferences, - and documents. It usually contains most of the other folders. If a - requested folder does not exist, the home folder can be considered a safe - fallback to store a user's documents. */ - SDL_FOLDER_HOME, - /** The folder of files that are displayed on the desktop. Note that the - existence of a desktop folder does not guarantee that the system does - show icons on its desktop; certain GNU/Linux distros with a graphical - environment may not have desktop icons. */ - SDL_FOLDER_DESKTOP, - /** User document files, possibly application-specific. This is a good - place to save a user's projects. */ - SDL_FOLDER_DOCUMENTS, - /** Standard folder for user files downloaded from the internet. */ - SDL_FOLDER_DOWNLOADS, - /** Music files that can be played using a standard music player (mp3, - ogg...). */ - SDL_FOLDER_MUSIC, - /** Image files that can be displayed using a standard viewer (png, - jpg...). */ - SDL_FOLDER_PICTURES, - /** Files that are meant to be shared with other users on the same - computer. */ - SDL_FOLDER_PUBLICSHARE, - /** Save files for games. */ - SDL_FOLDER_SAVEDGAMES, - /** Application screenshots. */ - SDL_FOLDER_SCREENSHOTS, - /** Template files to be used when the user requests the desktop environment - to create a new file in a certain folder, such as "New Text File.txt". - Any file in the Templates folder can be used as a starting point for a - new file. */ - SDL_FOLDER_TEMPLATES, - /** Video files that can be played using a standard video player (mp4, - webm...). */ - SDL_FOLDER_VIDEOS, - /** total number of types in this enum, not a folder type by itself. */ - SDL_FOLDER_TOTAL + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ } SDL_Folder; /** @@ -226,13 +216,24 @@ typedef enum SDL_Folder * \returns either a null-terminated C string containing the full path to the * folder, or NULL if an error happened. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder); /* Abstract filesystem interface */ +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ typedef enum SDL_PathType { SDL_PATHTYPE_NONE, /**< path does not exist */ @@ -241,19 +242,27 @@ typedef enum SDL_PathType SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */ } SDL_PathType; +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ typedef struct SDL_PathInfo { - SDL_PathType type; /* the path type */ - Uint64 size; /* the file size in bytes */ - SDL_Time create_time; /* the time when the path was created */ - SDL_Time modify_time; /* the last time the path was modified */ - SDL_Time access_time; /* the last time the path was read */ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ } SDL_PathInfo; /** - * Flags for path matching + * Flags for path matching. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GlobDirectory * \sa SDL_GlobStorageDirectory @@ -263,73 +272,160 @@ typedef Uint32 SDL_GlobFlags; #define SDL_GLOB_CASEINSENSITIVE (1u << 0) /** - * Create a directory. + * Create a directory, and any missing parent directories. + * + * This reports success if `path` already exists as a directory. + * + * If parent directories are missing, it will also create them. Note that if + * this fails, it will not remove any parent directories it already made. * * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateDirectory(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); -/* Callback for directory enumeration. Return 1 to keep enumerating, - 0 to stop enumerating (no error), -1 to stop enumerating and - report an error. `dirname` is the directory being enumerated, - `fname` is the enumerated entry. */ -typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param dirname the directory that is being enumerated. + * \param fname the next entry in the enumeration. + * \returns how the enumeration should proceed. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); /** * Enumerate a directory through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. * * \param path the path of the directory to enumerate. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory. * - * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. * - * \since This function is available since SDL 3.0.0. + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemovePath(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); /** * Rename a file or directory. * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); /** * Copy a file. * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `newpath`'s previous contents will be gone, replaced with + * an incomplete copy of the data. To avoid this risk, it is recommended that + * the app copy to a temporary file in the same directory as `newpath`, and if + * the copy is successful, use SDL_RenamePath() to replace `newpath` with the + * temporary file. This will ensure that reads of `newpath` will either see a + * complete copy of the data, or it will see the pre-copy state of `newpath`. + * + * This function attempts to synchronize the newly-copied data to disk before + * returning, if the platform allows it, so that the renaming trick will not + * have a problem in a system crash or power failure, where the file could be + * renamed but the contents never made it from the system file cache to the + * physical disk. + * + * If the copy fails for any reason, the state of `newpath` is undefined. It + * might be half a copy, it might be the untouched data of what was already + * there, or it might be a zero-byte file, etc. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); /** * Get information about a filesystem path. @@ -337,21 +433,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const cha * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); /** * Enumerate a directory tree, filtered by pattern, and return a list. * * Files are filtered out if they don't match the string in `pattern`, which - * may contain wildcard characters '*' (match everything) and '?' (match one + * may contain wildcard characters '\*' (match everything) and '?' (match one * character). If pattern is NULL, no filtering is done and all results are * returned. Subdirectories are permitted, and are specified with a path - * separator of '/'. Wildcard characters '*' and '?' never match a path + * separator of '/'. Wildcard characters '\*' and '?' never match a path * separator. * * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching @@ -373,10 +469,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count); +/** + * Get what the system believes is the "current working directory." + * + * For systems without a concept of a current working directory, this will + * still attempt to provide something reasonable. + * + * SDL does not provide a means to _change_ the current working directory; for + * platforms without this concept, this would cause surprises with file access + * outside of SDL. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns a UTF-8 string of the current working directory in + * platform-dependent notation. NULL if there's a problem. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gamepad.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gamepad.h index 3d2d726..264f763 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gamepad.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gamepad.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,6 +51,24 @@ * If you would like to receive gamepad updates while the application is in * the background, you should set the following hint before calling * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. */ #ifndef SDL_gamepad_h_ @@ -58,9 +76,11 @@ #include #include -#include -#include +#include #include +#include +#include +#include #include #include @@ -72,7 +92,7 @@ extern "C" { /** * The structure used to identify an SDL gamepad * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Gamepad SDL_Gamepad; @@ -98,7 +118,7 @@ typedef enum SDL_GamepadType SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_GAMEPAD_TYPE_MAX + SDL_GAMEPAD_TYPE_COUNT } SDL_GamepadType; /** @@ -122,15 +142,15 @@ typedef enum SDL_GamepadType * You can query the labels for the face buttons using * SDL_GetGamepadButtonLabel() * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButton { SDL_GAMEPAD_BUTTON_INVALID = -1, - SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */ - SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */ - SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */ - SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */ + SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */ + SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */ + SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */ + SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */ SDL_GAMEPAD_BUTTON_BACK, SDL_GAMEPAD_BUTTON_GUIDE, SDL_GAMEPAD_BUTTON_START, @@ -142,18 +162,18 @@ typedef enum SDL_GamepadButton SDL_GAMEPAD_BUTTON_DPAD_DOWN, SDL_GAMEPAD_BUTTON_DPAD_LEFT, SDL_GAMEPAD_BUTTON_DPAD_RIGHT, - SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ - SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */ - SDL_GAMEPAD_BUTTON_MISC2, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC3, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC4, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC5, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC6, /* Additional button */ - SDL_GAMEPAD_BUTTON_MAX + SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */ + SDL_GAMEPAD_BUTTON_COUNT } SDL_GamepadButton; /** @@ -165,7 +185,7 @@ typedef enum SDL_GamepadButton * For a complete set, you should look at the button and gamepad type and have * a set of symbols that work well with your art style. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButtonLabel { @@ -192,7 +212,7 @@ typedef enum SDL_GamepadButtonLabel * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the * same range that will be reported by the lower-level SDL_GetJoystickAxis(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadAxis { @@ -203,7 +223,7 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_RIGHTY, SDL_GAMEPAD_AXIS_LEFT_TRIGGER, SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, - SDL_GAMEPAD_AXIS_MAX + SDL_GAMEPAD_AXIS_COUNT } SDL_GamepadAxis; /** @@ -214,7 +234,7 @@ typedef enum SDL_GamepadAxis * gamepad. This enum is used as part of SDL_GamepadBinding to specify those * mappings. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadBindingType { @@ -235,7 +255,7 @@ typedef enum SDL_GamepadBindingType * more with a simple text string. Those strings are parsed into a collection * of these structs to make it easier to operate on the data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetGamepadBindings */ @@ -293,6 +313,9 @@ typedef struct SDL_GamepadBinding * * Buttons can be used as a gamepad axes and vice versa. * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * * This string shows an example of a valid mapping for a gamepad: * * ```c @@ -305,10 +328,15 @@ typedef struct SDL_GamepadBinding * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); @@ -321,6 +349,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -330,21 +361,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * constrained environment. * * \param src the data stream for the mappings to be added. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the number of mappings added or -1 on failure; call SDL_GetError() * for more information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromFile * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ -extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); /** * Load a set of gamepad mappings from a file. @@ -355,6 +389,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -365,12 +402,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); @@ -379,12 +419,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file) * * This will generate gamepad events as needed if device mappings change. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. @@ -396,7 +436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); @@ -408,7 +448,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); * information. This should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUID @@ -425,7 +465,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid); * available; call SDL_GetError() for more information. This should * be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMappingForID @@ -442,26 +482,26 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); * \param instance_id the joystick instance ID. * \param mapping the mapping to use for this device, or NULL to clear the * mapping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMapping */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); /** * Return whether a gamepad is currently connected. * - * \returns SDL_TRUE if a gamepad is connected, SDL_FALSE otherwise. + * \returns true if a gamepad is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. @@ -472,7 +512,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasGamepad * \sa SDL_OpenGamepad @@ -483,15 +523,15 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); * Check if the given joystick is supported by the gamepad interface. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the given joystick is supported by the gamepad - * interface, SDL_FALSE if it isn't or it's an invalid index. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks * \sa SDL_OpenGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); /** * Get the implementation dependent name of a gamepad. @@ -502,7 +542,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); * \returns the name of the selected gamepad. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadName * \sa SDL_GetGamepads @@ -518,7 +558,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID * \returns the path of the selected gamepad. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPath * \sa SDL_GetGamepads @@ -533,7 +573,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepads @@ -549,7 +589,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID in * \returns the GUID of the selected gamepad. If called on an invalid index, * this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString * \sa SDL_GetGamepads @@ -566,7 +606,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID inst * \returns the USB vendor ID of the selected gamepad. If called on an invalid * index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendor * \sa SDL_GetGamepads @@ -583,7 +623,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID inst * \returns the USB product ID of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProduct * \sa SDL_GetGamepads @@ -600,7 +640,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID ins * \returns the product version of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersion * \sa SDL_GetGamepads @@ -615,7 +655,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_Joystic * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadType * \sa SDL_GetGamepads @@ -631,7 +671,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_Joystick * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepads @@ -648,7 +688,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys * \returns the mapping string. Returns NULL if no mapping is available. This * should be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads * \sa SDL_GetGamepadMapping @@ -662,7 +702,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID ins * \returns a gamepad identifier or NULL if an error occurred; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseGamepad * \sa SDL_IsGamepad @@ -677,7 +717,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instanc * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); @@ -687,7 +727,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID in * \param player_index the player index, which different from the instance ID. * \returns the SDL_Gamepad associated with a player index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_SetGamepadPlayerIndex @@ -717,7 +757,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int play * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); @@ -735,7 +775,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa * \returns the instance ID of the specified gamepad on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); @@ -747,7 +787,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad * \returns the implementation dependent name for the gamepad, or NULL if * there is no name or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadNameForID */ @@ -761,7 +801,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad * \returns the implementation dependent path for the gamepad, or NULL if * there is no path or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPathForID */ @@ -774,7 +814,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID */ @@ -787,7 +827,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRealGamepadTypeForID */ @@ -801,7 +841,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad * * \param gamepad the gamepad object to query. * \returns the player index for gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadPlayerIndex */ @@ -813,14 +853,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to adjust. * \param player_index player index to assign to this gamepad, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); /** * Get the USB vendor ID of an opened gamepad, if available. @@ -830,7 +870,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *game * \param gamepad the gamepad object to query. * \returns the USB vendor ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendorForID */ @@ -844,7 +884,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductForID */ @@ -858,7 +898,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersionForID */ @@ -872,7 +912,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gam * \param gamepad the gamepad object to query. * \returns the gamepad firmware version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); @@ -884,7 +924,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga * \param gamepad the gamepad object to query. * \returns the serial number, or NULL if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); @@ -897,7 +937,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamep * \param gamepad the gamepad object to query. * \returns the gamepad handle, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); @@ -909,7 +949,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepa * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); @@ -929,7 +969,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnection * battery. * \returns the current battery state. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); @@ -938,12 +978,12 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad * * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). - * \returns SDL_TRUE if the gamepad has been opened and is currently - * connected, or SDL_FALSE if not. + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** * Get the underlying joystick from a gamepad. @@ -961,7 +1001,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); @@ -973,12 +1013,12 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g * * \param enabled whether to process gamepad events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadEventsEnabled * \sa SDL_UpdateGamepads */ -extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); /** * Query the state of gamepad event processing. @@ -986,14 +1026,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * and check the state of the gamepad when you want gamepad information. * - * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE - * otherwise. + * \returns true if gamepad events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); /** * Get the SDL joystick layer bindings for a gamepad. @@ -1005,7 +1044,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); @@ -1016,7 +1055,7 @@ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gam * enabled. Under such circumstances, it will not be necessary to call this * function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); @@ -1032,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); * \returns the SDL_GamepadType enum corresponding to the input string, or * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForType */ @@ -1046,7 +1085,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeFromString */ @@ -1068,7 +1107,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_Gamepad * \returns the SDL_GamepadAxis enum corresponding to the input string, or * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForAxis */ @@ -1082,7 +1121,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAxisFromString */ @@ -1096,14 +1135,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad * * \param gamepad a gamepad. * \param axis an axis enum value (an SDL_GamepadAxis value). - * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. + * \returns true if the gamepad has this axis, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); /** * Get the current state of an axis control on a gamepad. @@ -1122,7 +1161,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD * \returns axis state (including 0) on success or 0 (also) on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis * \sa SDL_GetGamepadButton @@ -1141,7 +1180,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_ * \returns the SDL_GamepadButton enum corresponding to the input string, or * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForButton */ @@ -1155,7 +1194,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonFromString */ @@ -1169,28 +1208,27 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep * * \param gamepad a gamepad. * \param button a button enum value (an SDL_GamepadButton value). - * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. + * \returns true if the gamepad has this button, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the current state of a button on a gamepad. * * \param gamepad a gamepad. * \param button a button index (one of the SDL_GamepadButton values). - * \returns 1 for pressed state or 0 for not pressed state or failure; call - * SDL_GetError() for more information. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the label of a button on a gamepad. @@ -1199,7 +1237,7 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabel */ @@ -1212,7 +1250,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabelForType */ @@ -1224,7 +1262,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL * \param gamepad a gamepad. * \returns number of touchpads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ @@ -1238,7 +1276,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad) * \param touchpad a touchpad. * \returns number of supported simultaneous fingers. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTouchpadFinger * \sa SDL_GetNumGamepadTouchpads @@ -1251,35 +1289,36 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga * \param gamepad a gamepad. * \param touchpad a touchpad. * \param finger a finger. - * \param state filled with state. - * \param x filled with x position, normalized 0 to 1, with the origin in the - * upper left. - * \param y filled with y position, normalized 0 to 1, with the origin in the - * upper left. - * \param pressure filled with pressure value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); /** * Return whether a gamepad has a particular sensor. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. + * \returns true if the sensor exists, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadSensorData * \sa SDL_GetGamepadSensorDataRate * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Set whether data reporting for a gamepad sensor is enabled. @@ -1287,28 +1326,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, * \param gamepad the gamepad to update. * \param type the type of sensor to enable/disable. * \param enabled whether data reporting should be enabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasSensor * \sa SDL_GamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); /** * Query whether sensor data reporting is enabled for a gamepad. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. + * \returns true if the sensor is enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Get the data rate (number of events per second) of a gamepad sensor. @@ -1317,7 +1356,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep * \param type the type of sensor to query. * \returns the data rate, or 0.0f if the data rate is not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); @@ -1331,12 +1370,12 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game * \param type the type of sensor to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); /** * Start a rumble effect on a gamepad. @@ -1353,12 +1392,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamep * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the gamepad's triggers. @@ -1379,14 +1418,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uin * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a gamepad's LED color. @@ -1401,12 +1440,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *game * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** * Send a gamepad specific effect packet. @@ -1414,12 +1453,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uin * \param gamepad the gamepad to affect. * \param data the data to send to the gamepad. * \param size the size of the data to send to the gamepad. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); /** * Close a gamepad previously opened with SDL_OpenGamepad(). @@ -1427,7 +1466,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenGamepad */ @@ -1441,7 +1480,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); * \param button a button on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis */ @@ -1454,7 +1493,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt * \param axis an axis on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForButton */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gpu.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gpu.h index bba47cc..fa870a5 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gpu.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_gpu.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,281 @@ /** * # CategoryGPU * - * Include file for SDL GPU API functions + * The GPU API offers a cross-platform way for apps to talk to modern graphics + * hardware. It offers both 3D graphics and compute support, in the style of + * Metal, Vulkan, and Direct3D 12. + * + * A basic workflow might be something like this: + * + * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to + * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you + * can render offscreen entirely, perhaps for image processing, and not use a + * window at all. + * + * Next the app prepares static data (things that are created once and used + * over and over). For example: + * + * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader(). + * - Vertex buffers (arrays of geometry data) and other data rendering will + * need: use SDL_UploadToGPUBuffer(). + * - Textures (images): use SDL_UploadToGPUTexture(). + * - Samplers (how textures should be read from): use SDL_CreateGPUSampler(). + * - Render pipelines (precalculated rendering state): use + * SDL_CreateGPUGraphicsPipeline() + * + * To render, the app creates one or more command buffers, with + * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering + * instructions that will be submitted to the GPU in batch. Complex scenes can + * use multiple command buffers, maybe configured across multiple threads in + * parallel, as long as they are submitted in the correct order, but many apps + * will just need one command buffer per frame. + * + * Rendering can happen to a texture (what other APIs call a "render target") + * or it can happen to the swapchain texture (which is just a special texture + * that represents a window's contents). The app can use + * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. */ #ifndef SDL_gpu_h_ @@ -44,132 +318,394 @@ extern "C" { /* Type Declarations */ +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ typedef struct SDL_GPUFence SDL_GPUFence; +/** + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUPrimitiveType { - SDL_GPU_PRIMITIVETYPE_POINTLIST, - SDL_GPU_PRIMITIVETYPE_LINELIST, - SDL_GPU_PRIMITIVETYPE_LINESTRIP, - SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, - SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ } SDL_GPUPrimitiveType; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPULoadOp { - SDL_GPU_LOADOP_LOAD, - SDL_GPU_LOADOP_CLEAR, - SDL_GPU_LOADOP_DONT_CARE + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ } SDL_GPULoadOp; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPUStoreOp { - SDL_GPU_STOREOP_STORE, - SDL_GPU_STOREOP_DONT_CARE + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ } SDL_GPUStoreOp; +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUIndexElementSize { - SDL_GPU_INDEXELEMENTSIZE_16BIT, - SDL_GPU_INDEXELEMENTSIZE_32BIT + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ } SDL_GPUIndexElementSize; -/* Texture format support varies depending on driver, hardware, and usage flags. - * In general, you should use SDL_GPUTextureSupportsFormat to query if a format - * is supported before using it. However, there are a few guaranteed formats. +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE * * For SAMPLER usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R8G8_SNORM - * - R8G8B8A8_SNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB - * - D16_UNORM + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM * * For COLOR_TARGET usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB * * For STORAGE usages, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - R8G8B8A8_SNORM - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT * - * For DEPTH_STENCIL_TARGET usage, the following formats are universally supported: - * - D16_UNORM - * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT - * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT * - * Unless D16_UNORM is sufficient for your purposes, always check which - * of D24/D32 is supported before creating a depth-stencil texture! + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat */ typedef enum SDL_GPUTextureFormat { - SDL_GPU_TEXTUREFORMAT_INVALID = -1, + SDL_GPU_TEXTUREFORMAT_INVALID, /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, - SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, - SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, - SDL_GPU_TEXTUREFORMAT_R8_UNORM, - SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, /* Compressed Unsigned Normalized Float Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC1_UNORM, - SDL_GPU_TEXTUREFORMAT_BC2_UNORM, - SDL_GPU_TEXTUREFORMAT_BC3_UNORM, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, /* Signed Float Color Formats */ SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, @@ -177,6 +713,8 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, /* Unsigned Integer Color Formats */ SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_UINT, @@ -184,48 +722,153 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, /* SRGB Unsigned Normalized Color Formats */ SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, /* Compressed SRGB Unsigned Normalized Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC3_UNORM_SRGB, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, /* Depth Formats */ SDL_GPU_TEXTUREFORMAT_D16_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D32_FLOAT, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, - SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT } SDL_GPUTextureFormat; -typedef enum SDL_GPUTextureUsageFlagBits -{ - SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT = 0x00000001, - SDL_GPU_TEXTUREUSAGE_COLOR_TARGET_BIT = 0x00000002, - SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET_BIT = 0x00000004, - SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUTextureUsageFlagBits; - +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef Uint32 SDL_GPUTextureUsageFlags; +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef enum SDL_GPUTextureType { - SDL_GPU_TEXTURETYPE_2D, - SDL_GPU_TEXTURETYPE_2D_ARRAY, - SDL_GPU_TEXTURETYPE_3D, - SDL_GPU_TEXTURETYPE_CUBE + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ } SDL_GPUTextureType; +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ typedef enum SDL_GPUSampleCount { - SDL_GPU_SAMPLECOUNT_1, - SDL_GPU_SAMPLECOUNT_2, - SDL_GPU_SAMPLECOUNT_4, - SDL_GPU_SAMPLECOUNT_8 + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ } SDL_GPUSampleCount; + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_GPUCubeMapFace { SDL_GPU_CUBEMAPFACE_POSITIVEX, @@ -236,45 +879,87 @@ typedef enum SDL_GPUCubeMapFace SDL_GPU_CUBEMAPFACE_NEGATIVEZ } SDL_GPUCubeMapFace; -typedef enum SDL_GPUBufferUsageFlagBits -{ - SDL_GPU_BUFFERUSAGE_VERTEX_BIT = 0x00000001, - SDL_GPU_BUFFERUSAGE_INDEX_BIT = 0x00000002, - SDL_GPU_BUFFERUSAGE_INDIRECT_BIT = 0x00000004, - SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUBufferUsageFlagBits; - +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ typedef Uint32 SDL_GPUBufferUsageFlags; +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef enum SDL_GPUTransferBufferUsage { SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD } SDL_GPUTransferBufferUsage; +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef enum SDL_GPUShaderStage { SDL_GPU_SHADERSTAGE_VERTEX, SDL_GPU_SHADERSTAGE_FRAGMENT } SDL_GPUShaderStage; -typedef enum SDL_GPUShaderFormatFlagBits -{ - SDL_GPU_SHADERFORMAT_INVALID = 0x00000000, - SDL_GPU_SHADERFORMAT_SECRET = 0x00000001, /* NDA'd platforms */ - SDL_GPU_SHADERFORMAT_SPIRV = 0x00000002, /* Vulkan */ - SDL_GPU_SHADERFORMAT_DXBC = 0x00000004, /* D3D11 (Shader Model 5_0) */ - SDL_GPU_SHADERFORMAT_DXIL = 0x00000008, /* D3D12 */ - SDL_GPU_SHADERFORMAT_MSL = 0x00000010, /* Metal */ - SDL_GPU_SHADERFORMAT_METALLIB = 0x00000020, /* Metal */ -} SDL_GPUShaderFormatFlagBits; - +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef Uint32 SDL_GPUShaderFormat; +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexElementFormat { + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + /* 32-bit Signed Integers */ SDL_GPU_VERTEXELEMENTFORMAT_INT, SDL_GPU_VERTEXELEMENTFORMAT_INT2, @@ -330,125 +1015,230 @@ typedef enum SDL_GPUVertexElementFormat SDL_GPU_VERTEXELEMENTFORMAT_HALF4 } SDL_GPUVertexElementFormat; +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexInputRate { - SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, - SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ } SDL_GPUVertexInputRate; +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFillMode { - SDL_GPU_FILLMODE_FILL, - SDL_GPU_FILLMODE_LINE + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ } SDL_GPUFillMode; +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCullMode { - SDL_GPU_CULLMODE_NONE, - SDL_GPU_CULLMODE_FRONT, - SDL_GPU_CULLMODE_BACK + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ } SDL_GPUCullMode; +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFrontFace { - SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, - SDL_GPU_FRONTFACE_CLOCKWISE + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ } SDL_GPUFrontFace; +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCompareOp { - SDL_GPU_COMPAREOP_NEVER, - SDL_GPU_COMPAREOP_LESS, - SDL_GPU_COMPAREOP_EQUAL, - SDL_GPU_COMPAREOP_LESS_OR_EQUAL, - SDL_GPU_COMPAREOP_GREATER, - SDL_GPU_COMPAREOP_NOT_EQUAL, - SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, - SDL_GPU_COMPAREOP_ALWAYS + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ } SDL_GPUCompareOp; +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUStencilOp { - SDL_GPU_STENCILOP_KEEP, - SDL_GPU_STENCILOP_ZERO, - SDL_GPU_STENCILOP_REPLACE, - SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_INVERT, - SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, - SDL_GPU_STENCILOP_DECREMENT_AND_WRAP + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ } SDL_GPUStencilOp; +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendOp { - SDL_GPU_BLENDOP_ADD, - SDL_GPU_BLENDOP_SUBTRACT, - SDL_GPU_BLENDOP_REVERSE_SUBTRACT, - SDL_GPU_BLENDOP_MIN, - SDL_GPU_BLENDOP_MAX + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ } SDL_GPUBlendOp; +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendFactor { - SDL_GPU_BLENDFACTOR_ZERO, - SDL_GPU_BLENDFACTOR_ONE, - SDL_GPU_BLENDFACTOR_SRC_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, - SDL_GPU_BLENDFACTOR_DST_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_DST_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, - SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ } SDL_GPUBlendFactor; -typedef enum SDL_GPUColorComponentFlagBits -{ - SDL_GPU_COLORCOMPONENT_R_BIT = 0x00000001, - SDL_GPU_COLORCOMPONENT_G_BIT = 0x00000002, - SDL_GPU_COLORCOMPONENT_B_BIT = 0x00000004, - SDL_GPU_COLORCOMPONENT_A_BIT = 0x00000008 -} SDL_GPUColorComponentFlagBits; - +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef Uint8 SDL_GPUColorComponentFlags; +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUFilter { - SDL_GPU_FILTER_NEAREST, - SDL_GPU_FILTER_LINEAR + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ } SDL_GPUFilter; +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerMipmapMode { - SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, - SDL_GPU_SAMPLERMIPMAPMODE_LINEAR + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ } SDL_GPUSamplerMipmapMode; +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerAddressMode { - SDL_GPU_SAMPLERADDRESSMODE_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ } SDL_GPUSamplerAddressMode; -/* - * VSYNC: - * Waits for vblank before presenting. - * If there is a pending image to present, the new image is enqueued for presentation. - * Disallows tearing at the cost of visual latency. - * When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight. - * IMMEDIATE: - * Immediately presents. - * Lowest latency option, but tearing may occur. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. - * MAILBOX: - * Waits for vblank before presenting. No tearing is possible. - * If there is a pending image to present, the pending image is replaced by the new image. - * Similar to VSYNC, but with reduced visual latency. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUPresentMode { @@ -457,493 +1247,866 @@ typedef enum SDL_GPUPresentMode SDL_GPU_PRESENTMODE_MAILBOX } SDL_GPUPresentMode; -/* - * SDR: - * B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. Blends raw pixel values. - * SDR_LINEAR: - * B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. Blends in linear space. - * HDR_EXTENDED_LINEAR: - * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. Blends in linear space. - * HDR10_ST2048: - * A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding. Blends raw pixel values. (TODO: verify this) +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUSwapchainComposition { SDL_GPU_SWAPCHAINCOMPOSITION_SDR, SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, - SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 } SDL_GPUSwapchainComposition; -typedef enum SDL_GPUDriver -{ - SDL_GPU_DRIVER_INVALID = -1, - SDL_GPU_DRIVER_SECRET, /* NDA'd platforms */ - SDL_GPU_DRIVER_VULKAN, - SDL_GPU_DRIVER_D3D11, - SDL_GPU_DRIVER_D3D12, - SDL_GPU_DRIVER_METAL -} SDL_GPUDriver; - /* Structures */ -typedef struct SDL_GPUDepthStencilValue -{ - float depth; - Uint8 stencil; -} SDL_GPUDepthStencilValue; - +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ typedef struct SDL_GPUViewport { - float x; - float y; - float w; - float h; - float minDepth; - float maxDepth; + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ } SDL_GPUViewport; +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureTransferInfo { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; /* starting location of the image data */ - Uint32 imagePitch; /* number of pixels from one row to the next */ - Uint32 imageHeight; /* number of rows from one layer/depth-slice to the next */ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ } SDL_GPUTextureTransferInfo; +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUTransferBufferLocation { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ } SDL_GPUTransferBufferLocation; +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + */ typedef struct SDL_GPUTextureLocation { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ } SDL_GPUTextureLocation; +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; - Uint32 w; - Uint32 h; - Uint32 d; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ } SDL_GPUTextureRegion; +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ typedef struct SDL_GPUBlitRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; - Uint32 x; - Uint32 y; - Uint32 w; - Uint32 h; + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ } SDL_GPUBlitRegion; +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + */ typedef struct SDL_GPUBufferLocation { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ } SDL_GPUBufferLocation; +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUBufferRegion { - SDL_GPUBuffer *buffer; - Uint32 offset; - Uint32 size; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ } SDL_GPUBufferRegion; -/* Note that the `firstVertex` and `firstInstance` parameters are NOT compatible with - * built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If - * your shader depends on these variables, the correlating draw call parameter MUST - * be 0. +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect */ typedef struct SDL_GPUIndirectDrawCommand { - Uint32 vertexCount; /* number of vertices to draw */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstVertex; /* index of the first vertex to draw */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ typedef struct SDL_GPUIndexedIndirectDrawCommand { - Uint32 indexCount; /* number of vertices to draw per instance */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstIndex; /* base index within the index buffer */ - Sint32 vertexOffset; /* value added to vertex index before indexing into the vertex buffer */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndexedIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ typedef struct SDL_GPUIndirectDispatchCommand { - Uint32 groupCountX; - Uint32 groupCountY; - Uint32 groupCountZ; + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ } SDL_GPUIndirectDispatchCommand; /* State structures */ +/** + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef struct SDL_GPUSamplerCreateInfo { - SDL_GPUFilter minFilter; - SDL_GPUFilter magFilter; - SDL_GPUSamplerMipmapMode mipmapMode; - SDL_GPUSamplerAddressMode addressModeU; - SDL_GPUSamplerAddressMode addressModeV; - SDL_GPUSamplerAddressMode addressModeW; - float mipLodBias; - SDL_bool anisotropyEnable; - float maxAnisotropy; - SDL_bool compareEnable; - SDL_GPUCompareOp compareOp; - float minLod; - float maxLod; + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUSamplerCreateInfo; -typedef struct SDL_GPUVertexBinding +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexBufferDescription { - Uint32 binding; - Uint32 stride; - SDL_GPUVertexInputRate inputRate; - Uint32 instanceStepRate; /* ignored unless inputRate is INSTANCE */ -} SDL_GPUVertexBinding; + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */ +} SDL_GPUVertexBufferDescription; +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + */ typedef struct SDL_GPUVertexAttribute { - Uint32 location; - Uint32 binding; - SDL_GPUVertexElementFormat format; - Uint32 offset; + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ } SDL_GPUVertexAttribute; +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + */ typedef struct SDL_GPUVertexInputState { - const SDL_GPUVertexBinding *vertexBindings; - Uint32 vertexBindingCount; - const SDL_GPUVertexAttribute *vertexAttributes; - Uint32 vertexAttributeCount; + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ } SDL_GPUVertexInputState; +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ typedef struct SDL_GPUStencilOpState { - SDL_GPUStencilOp failOp; - SDL_GPUStencilOp passOp; - SDL_GPUStencilOp depthFailOp; - SDL_GPUCompareOp compareOp; + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ } SDL_GPUStencilOpState; -typedef struct SDL_GPUColorAttachmentBlendState +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState { - SDL_bool blendEnable; - SDL_GPUBlendFactor srcColorBlendFactor; - SDL_GPUBlendFactor dstColorBlendFactor; - SDL_GPUBlendOp colorBlendOp; - SDL_GPUBlendFactor srcAlphaBlendFactor; - SDL_GPUBlendFactor dstAlphaBlendFactor; - SDL_GPUBlendOp alphaBlendOp; - SDL_GPUColorComponentFlags colorWriteMask; -} SDL_GPUColorAttachmentBlendState; + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef struct SDL_GPUShaderCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - SDL_GPUShaderStage stage; - Uint32 samplerCount; - Uint32 storageTextureCount; - Uint32 storageBufferCount; - Uint32 uniformBufferCount; + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUShaderCreateInfo; +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + */ typedef struct SDL_GPUTextureCreateInfo { - SDL_GPUTextureType type; - SDL_GPUTextureFormat format; - SDL_GPUTextureUsageFlags usageFlags; - Uint32 width; - Uint32 height; - Uint32 layerCountOrDepth; - Uint32 levelCount; - SDL_GPUSampleCount sampleCount; + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTextureCreateInfo; -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" - +/** + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + */ typedef struct SDL_GPUBufferCreateInfo { - SDL_GPUBufferUsageFlags usageFlags; - Uint32 sizeInBytes; + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUBufferCreateInfo; +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef struct SDL_GPUTransferBufferCreateInfo { - SDL_GPUTransferBufferUsage usage; - Uint32 sizeInBytes; + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTransferBufferCreateInfo; /* Pipeline state structures */ +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if + * enable_depth_clip is true. If you rely on this clamp+clip behavior, + * consider enabling depth clip and then manually clamping depth in your + * fragment shaders on Metal and Vulkan. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPURasterizerState { - SDL_GPUFillMode fillMode; - SDL_GPUCullMode cullMode; - SDL_GPUFrontFace frontFace; - SDL_bool depthBiasEnable; - float depthBiasConstantFactor; - float depthBiasClamp; - float depthBiasSlopeFactor; + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; } SDL_GPURasterizerState; +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUMultisampleState { - SDL_GPUSampleCount sampleCount; - Uint32 sampleMask; + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */ + bool enable_mask; /**< Enables sample masking. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUMultisampleState; +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUDepthStencilState { - SDL_bool depthTestEnable; - SDL_bool depthWriteEnable; - SDL_GPUCompareOp compareOp; - SDL_bool stencilTestEnable; - SDL_GPUStencilOpState backStencilState; - SDL_GPUStencilOpState frontStencilState; - Uint8 compareMask; - Uint8 writeMask; - Uint8 reference; + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUDepthStencilState; -typedef struct SDL_GPUColorAttachmentDescription +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription { - SDL_GPUTextureFormat format; - SDL_GPUColorAttachmentBlendState blendState; -} SDL_GPUColorAttachmentDescription; + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; -typedef struct SDL_GPUGraphicsPipelineAttachmentInfo +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo { - SDL_GPUColorAttachmentDescription *colorAttachmentDescriptions; - Uint32 colorAttachmentCount; - SDL_bool hasDepthStencilAttachment; - SDL_GPUTextureFormat depthStencilFormat; -} SDL_GPUGraphicsPipelineAttachmentInfo; + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ typedef struct SDL_GPUGraphicsPipelineCreateInfo { - SDL_GPUShader *vertexShader; - SDL_GPUShader *fragmentShader; - SDL_GPUVertexInputState vertexInputState; - SDL_GPUPrimitiveType primitiveType; - SDL_GPURasterizerState rasterizerState; - SDL_GPUMultisampleState multisampleState; - SDL_GPUDepthStencilState depthStencilState; - SDL_GPUGraphicsPipelineAttachmentInfo attachmentInfo; - float blendConstants[4]; + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUGraphicsPipelineCreateInfo; +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + */ typedef struct SDL_GPUComputePipelineCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - Uint32 readOnlyStorageTextureCount; - Uint32 readOnlyStorageBufferCount; - Uint32 writeOnlyStorageTextureCount; - Uint32 writeOnlyStorageBufferCount; - Uint32 uniformBufferCount; - Uint32 threadCountX; - Uint32 threadCountY; - Uint32 threadCountZ; + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUComputePipelineCreateInfo; -typedef struct SDL_GPUColorAttachmentInfo +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo { - /* The texture that will be used as a color attachment by a render pass. */ - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; /* For 3D textures, you can bind an individual depth plane as an attachment. */ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; - /* Can be ignored by RenderPass if CLEAR is not used */ - SDL_FColor clearColor; - - /* Determines what is done with the texture at the beginning of the render pass. - * - * LOAD: - * Loads the data currently in the texture. - * - * CLEAR: - * Clears the texture to a single color. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the texture at the end of the render pass. - * - * STORE: - * Stores the results of the render pass in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and loadOp is not LOAD */ - SDL_bool cycle; -} SDL_GPUColorAttachmentInfo; - -typedef struct SDL_GPUDepthStencilAttachmentInfo +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo { - /* The texture that will be used as the depth stencil attachment by a render pass. */ - SDL_GPUTexture *texture; + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; - /* Can be ignored by the render pass if CLEAR is not used */ - SDL_GPUDepthStencilValue depthStencilClearValue; - - /* Determines what is done with the depth values at the beginning of the render pass. - * - * LOAD: - * Loads the depth values currently in the texture. - * - * CLEAR: - * Clears the texture to a single depth. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the depth values at the end of the render pass. - * - * STORE: - * Stores the depth results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* Determines what is done with the stencil values at the beginning of the render pass. - * - * LOAD: - * Loads the stencil values currently in the texture. - * - * CLEAR: - * Clears the texture to a single stencil value. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp stencilLoadOp; - - /* Determines what is done with the stencil values at the end of the render pass. - * - * STORE: - * Stores the stencil results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp stencilStoreOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and any load ops are not LOAD */ - SDL_bool cycle; -} SDL_GPUDepthStencilAttachmentInfo; +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; /* Binding structs */ +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + */ typedef struct SDL_GPUBufferBinding { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ } SDL_GPUBufferBinding; +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ typedef struct SDL_GPUTextureSamplerBinding { - SDL_GPUTexture *texture; - SDL_GPUSampler *sampler; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ } SDL_GPUTextureSamplerBinding; -typedef struct SDL_GPUStorageBufferWriteOnlyBinding +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding { - SDL_GPUBuffer *buffer; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; - /* if SDL_TRUE, cycles the buffer if it is bound. */ - SDL_bool cycle; -} SDL_GPUStorageBufferWriteOnlyBinding; - -typedef struct SDL_GPUStorageTextureWriteOnlyBinding +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - - /* if SDL_TRUE, cycles the texture if the texture is bound. */ - SDL_bool cycle; -} SDL_GPUStorageTextureWriteOnlyBinding; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; /* Functions */ /* Device */ /** - * Creates a GPU context. + * Checks for GPU runtime support. * - * \param formatFlags a bitflag indicating which shader formats the app is - * able to provide. - * \param debugMode enable debug mode properties and validations. + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. * \param name the preferred GPU driver, or NULL to let SDL pick the optimal * driver. - * \returns a GPU context on success or NULL on failure. + * \returns true if supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( - SDL_GPUShaderFormat formatFlags, - SDL_bool debugMode, + SDL_GPUShaderFormat format_flags, + bool debug_mode, const char *name); /** @@ -951,26 +2114,26 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * * These are the supported properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL`: enable debug mode properties - * and validations, defaults to SDL_TRUE. - * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL`: enable to prefer energy - * efficiency over maximum GPU performance, defaults to SDL_FALSE. + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to * use, if a specific one is desired. * * These are the current shader format properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to * provide shaders for an NDA platform. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to * provide SPIR-V shaders if applicable. - * - SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL`: The app is able to provide - * DXBC shaders if applicable - * `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to * provide DXIL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL`: The app is able to provide - * MSL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to * provide Metal shader libraries if applicable. * * With the D3D12 renderer: @@ -979,25 +2142,28 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * use for all vertex semantics, default is "TEXCOORD". * * \param props the properties to use. - * \returns a GPU context on success or NULL on failure. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( SDL_PropertiesID props); -#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" -#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL "SDL.gpu.device.create.shaders.secret" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" /** @@ -1005,70 +2171,132 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( * * \param device a GPU Context to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUDevice */ extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); /** - * Returns the backend used to create this GPU context. + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. * * \param device a GPU context to query. - * \returns an SDL_GPUDriver value, or SDL_GPU_DRIVER_INVALID on error. + * \returns the name of the device's driver, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); /* State Creation */ /** * Creates a pipeline object to be used in a compute workflow. * - * Shader resource bindings must be authored to follow a particular order. For - * SPIR-V shaders, use the following resource sets: 0: Read-only storage - * textures, followed by read-only storage buffers 1: Write-only storage - * textures, followed by write-only storage buffers 2: Uniform buffers + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Read-only storage textures, followed by read-only storage - * buffers For u registers: Write-only storage textures, followed by - * write-only storage buffers For b registers: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXIL shaders, use the following register order: (t[n], space0): - * Read-only storage textures, followed by read-only storage buffers (u[n], - * space1): Write-only storage textures, followed by write-only storage - * buffers (b[n], space2): Uniform buffers + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers * - * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, - * followed by write-only storage buffers, followed by write-only storage - * buffers For [[texture]]: Read-only storage textures, followed by write-only - * storage textures + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. * * \param device a GPU Context. - * \param computePipelineCreateInfo a struct describing the state of the - * requested compute pipeline. - * \returns a compute pipeline object on success, or NULL on failure. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUComputePipeline * \sa SDL_ReleaseGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipelineCreateInfo *computePipelineCreateInfo); + const SDL_GPUComputePipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" /** * Creates a pipeline object to be used in a graphics workflow. * - * \param device a GPU Context. - * \param pipelineCreateInfo a struct describing the state of the desired - * graphics pipeline. - * \returns a graphics pipeline object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUShader * \sa SDL_BindGPUGraphicsPipeline @@ -1076,26 +2304,36 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipelineCreateInfo *pipelineCreateInfo); + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" /** * Creates a sampler object to be used when binding textures in a graphics * workflow. * - * \param device a GPU Context. - * \param samplerCreateInfo a struct describing the state of the desired - * sampler. - * \returns a sampler object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUVertexSamplers * \sa SDL_BindGPUFragmentSamplers - * \sa SDL_ReleaseSampler + * \sa SDL_ReleaseGPUSampler */ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( SDL_GPUDevice *device, - SDL_GPUSamplerCreateInfo *samplerCreateInfo); + const SDL_GPUSamplerCreateInfo *createinfo); + +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" /** * Creates a shader to be used when creating a graphics pipeline. @@ -1103,46 +2341,78 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * Shader resource bindings must be authored to follow a particular order * depending on the shader format. * - * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: - * Sampled textures, followed by storage textures, followed by storage buffers - * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by - * storage textures, followed by storage buffers 3: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Sampled textures, followed by storage textures, followed by - * storage buffers For s registers: Samplers with indices corresponding to the - * sampled textures For b registers: Uniform buffers + * For vertex shaders: * - * For DXIL shaders, use the following register order: For vertex shaders: - * (t[n], space0): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space0): Samplers with indices corresponding to the - * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n], - * space2): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space2): Samplers with indices corresponding to the - * sampled textures (b[n], space3): Uniform buffers + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers * - * For MSL/metallib, use the following order: For [[texture]]: Sampled - * textures, followed by storage textures For [[sampler]]: Samplers with - * indices corresponding to the sampled textures For [[buffer]]: Uniform - * buffers, followed by storage buffers. Vertex buffer 0 is bound at - * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than - * manually authoring vertex buffer indices, use the [[stage_in]] attribute - * which will automatically use the vertex input information from the - * SDL_GPUPipeline. + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. * * \param device a GPU Context. - * \param shaderCreateInfo a struct describing the state of the desired - * shader. - * \returns a shader object on success, or NULL on failure. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUGraphicsPipeline * \sa SDL_ReleaseGPUShader */ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( SDL_GPUDevice *device, - SDL_GPUShaderCreateInfo *shaderCreateInfo); + const SDL_GPUShaderCreateInfo *createinfo); + +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" /** * Creates a texture object to be used in graphics or compute workflows. @@ -1157,12 +2427,36 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * - * \param device a GPU Context. - * \param textureCreateInfo a struct describing the state of the texture to - * create. - * \returns a texture object on success, or NULL on failure. + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the texture to create. + * \returns a texture object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture * \sa SDL_DownloadFromGPUTexture @@ -1177,7 +2471,15 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( */ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, - SDL_GPUTextureCreateInfo *textureCreateInfo); + const SDL_GPUTextureCreateInfo *createinfo); + +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" /** * Creates a buffer object to be used in graphics or compute workflows. @@ -1188,35 +2490,63 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * Note that certain combinations of usage flags are invalid. For example, a * buffer cannot have both the VERTEX and INDEX flags. * - * \param device a GPU Context. - * \param bufferCreateInfo a struct describing the state of the buffer to - * create. - * \returns a buffer object on success, or NULL on failure. + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer * \sa SDL_BindGPUVertexBuffers * \sa SDL_BindGPUIndexBuffer * \sa SDL_BindGPUVertexStorageBuffers * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect * \sa SDL_ReleaseGPUBuffer */ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( SDL_GPUDevice *device, - SDL_GPUBufferCreateInfo *bufferCreateInfo); + const SDL_GPUBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" /** * Creates a transfer buffer to be used when uploading to or downloading from * graphics resources. * - * \param device a GPU Context. - * \param transferBufferCreateInfo a struct describing the state of the - * transfer buffer to create. - * \returns a transfer buffer on success, or NULL on failure. + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer @@ -1226,20 +2556,28 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( */ extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBufferCreateInfo *transferBufferCreateInfo); + const SDL_GPUTransferBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" /* Debug Naming */ /** * Sets an arbitrary string constant to label a buffer. * - * Useful for debugging. + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. * * \param device a GPU Context. * \param buffer a buffer to attach the name to. * \param text a UTF-8 string constant to mark as the name of the buffer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( SDL_GPUDevice *device, @@ -1249,13 +2587,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( /** * Sets an arbitrary string constant to label a texture. * - * Useful for debugging. + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. * * \param device a GPU Context. * \param texture a texture to attach the name to. * \param text a UTF-8 string constant to mark as the name of the texture. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( SDL_GPUDevice *device, @@ -1267,13 +2612,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( * * Useful for debugging. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param text a UTF-8 string constant to insert as the label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *text); /** @@ -1290,28 +2635,28 @@ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( * pass rather than the command buffer. For best results, if you push a debug * group during a pass, always pop it in the same pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param name a UTF-8 string constant that names the group. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PopGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *name); /** * Ends the most-recently pushed debug group. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /* Disposal */ @@ -1323,7 +2668,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( * \param device a GPU context. * \param texture a texture to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( SDL_GPUDevice *device, @@ -1332,12 +2677,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( /** * Frees the given sampler as soon as it is safe to do so. * - * You must not reference the texture after calling this function. + * You must not reference the sampler after calling this function. * * \param device a GPU context. * \param sampler a sampler to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( SDL_GPUDevice *device, @@ -1351,7 +2696,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( * \param device a GPU context. * \param buffer a buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( SDL_GPUDevice *device, @@ -1363,13 +2708,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( * You must not reference the transfer buffer after calling this function. * * \param device a GPU context. - * \param transferBuffer a transfer buffer to be destroyed. + * \param transfer_buffer a transfer buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /** * Frees the given compute pipeline as soon as it is safe to do so. @@ -1377,13 +2722,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( * You must not reference the compute pipeline after calling this function. * * \param device a GPU context. - * \param computePipeline a compute pipeline to be destroyed. + * \param compute_pipeline a compute pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePipeline *compute_pipeline); /** * Frees the given shader as soon as it is safe to do so. @@ -1393,7 +2738,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( * \param device a GPU context. * \param shader a shader to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( SDL_GPUDevice *device, @@ -1405,29 +2750,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( * You must not reference the graphics pipeline after calling this function. * * \param device a GPU context. - * \param graphicsPipeline a graphics pipeline to be destroyed. + * \param graphics_pipeline a graphics pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipeline *graphicsPipeline); - -/* - * COMMAND BUFFERS - * - * Render state is managed via command buffers. - * When setting render state, that state is always local to the command buffer. - * - * Commands only begin execution on the GPU once Submit is called. - * Once the command buffer is submitted, it is no longer valid to use it. - * - * Command buffers are executed in submission order. If you submit command buffer A and then command buffer B - * all commands in A will begin executing before any command in B begins executing. - * - * In multi-threading scenarios, you should acquire and submit a command buffer on the same thread. - * As long as you satisfy this requirement, all functionality related to command buffers is thread-safe. - */ + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Acquire a command buffer. @@ -1437,10 +2766,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( * acquired on. The command buffer should be submitted on the thread it was * acquired on. * - * \param device a GPU context. - * \returns a command buffer. + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. * - * \since This function is available since SDL 3.0.0. + * \param device a GPU context. + * \returns a command buffer, or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence @@ -1448,118 +2785,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer( SDL_GPUDevice *device); -/* - * UNIFORM DATA - * - * Uniforms are for passing data to shaders. - * The uniform data will be constant across all executions of the shader. - * - * There are 4 available uniform slots per shader stage (vertex, fragment, compute). - * Uniform data pushed to a slot on a stage keeps its value throughout the command buffer - * until you call the relevant Push function on that slot again. - * - * For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, - * push the camera matrix at the start of the command buffer, and that data will be used for every - * subsequent draw call. - * - * It is valid to push uniform data during a render or compute pass. - * - * Uniforms are best for pushing small amounts of data. - * If you are pushing more than a matrix or two per call you should consider using a storage buffer instead. - */ +/* Uniform Data */ /** * Pushes data to a vertex uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the vertex uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the vertex uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a fragment uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the fragment uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the fragment uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); - -/* - * A NOTE ON CYCLING - * - * When using a command buffer, operations do not occur immediately - - * they occur some time after the command buffer is submitted. - * - * When a resource is used in a pending or active command buffer, it is considered to be "bound". - * When a resource is no longer used in any pending or active command buffers, it is considered to be "unbound". - * - * If data resources are bound, it is unspecified when that data will be unbound - * unless you acquire a fence when submitting the command buffer and wait on it. - * However, this doesn't mean you need to track resource usage manually. - * - * All of the functions and structs that involve writing to a resource have a "cycle" bool. - * GPUTransferBuffer, GPUBuffer, and GPUTexture all effectively function as ring buffers on internal resources. - * When cycle is SDL_TRUE, if the resource is bound, the cycle rotates to the next unbound internal resource, - * or if none are available, a new one is created. - * This means you don't have to worry about complex state tracking and synchronization as long as cycling is correctly employed. - * - * For example: you can call MapTransferBuffer, write texture data, UnmapTransferBuffer, and then UploadToTexture. - * The next time you write texture data to the transfer buffer, if you set the cycle param to SDL_TRUE, you don't have - * to worry about overwriting any data that is not yet uploaded. - * - * Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. - * If you set cycle to SDL_TRUE in the ColorAttachmentInfo struct, you can prevent this data dependency. - * - * Cycling will never undefine already bound data. - * When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. - * You must take care not to read undefined data. - * - * Note that when cycling a texture, the entire texture will be cycled, - * even if only part of the texture is used in the call, - * so you must consider the entire texture to contain undefined data after cycling. - * - * You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. - * It is OK to overwrite unreferenced data in a bound resource without cycling, - * but overwriting a section of data that has already been referenced will produce unexpected results. - */ + Uint32 length); /* Graphics State */ @@ -1574,212 +2854,240 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( * is called. You cannot begin another render pass, or begin a compute pass or * copy pass until you have ended the render pass. * - * \param commandBuffer a command buffer. - * \param colorAttachmentInfos an array of texture subresources with - * corresponding clear values and load/store ops. - * \param colorAttachmentCount the number of color attachments in the - * colorAttachmentInfos array. - * \param depthStencilAttachmentInfo a texture subresource with corresponding - * clear value and load/store ops, may be - * NULL. + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. * \returns a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPURenderPass */ extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUColorAttachmentInfo *colorAttachmentInfos, - Uint32 colorAttachmentCount, - SDL_GPUDepthStencilAttachmentInfo *depthStencilAttachmentInfo); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); /** * Binds a graphics pipeline on a render pass to be used in rendering. * * A graphics pipeline must be bound before making any draw calls. * - * \param renderPass a render pass handle. - * \param graphicsPipeline the graphics pipeline to bind. + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( - SDL_GPURenderPass *renderPass, - SDL_GPUGraphicsPipeline *graphicsPipeline); + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Sets the current viewport state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param viewport the viewport to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( - SDL_GPURenderPass *renderPass, - SDL_GPUViewport *viewport); + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); /** * Sets the current scissor state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param scissor the scissor area to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( - SDL_GPURenderPass *renderPass, - SDL_Rect *scissor); + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); /** * Binds vertex buffers on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param firstBinding the starting bind point for the vertex buffers. - * \param pBindings an array of SDL_GPUBufferBinding structs containing vertex - * buffers and offset values. - * \param bindingCount the number of bindings in the pBindings array. + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstBinding, - SDL_GPUBufferBinding *pBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); /** * Binds an index buffer on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param pBinding a pointer to a struct containing an index buffer and - * offset. - * \param indexElementSize whether the index values in the buffer are 16- or - * 32-bit. + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( - SDL_GPURenderPass *renderPass, - SDL_GPUBufferBinding *pBinding, - SDL_GPUIndexElementSize indexElementSize); + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); /** * Binds texture-sampler pairs for use on the vertex shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the vertex sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the vertex shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage texture to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage texture to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the vertex shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage buffer slot to begin binding from. - * \param storageBuffers an array of buffers. - * \param bindingCount the number of buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage buffer slot to begin binding from. + * \param storage_buffers an array of buffers. + * \param num_bindings the number of buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Binds texture-sampler pairs for use on the fragment shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the fragment sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the fragment shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the fragment shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffers. - * \param bindingCount the number of storage buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffers. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /* Drawing */ @@ -1789,100 +3097,101 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param indexCount the number of vertices to draw per instance. - * \param instanceCount the number of instances to draw. - * \param firstIndex the starting index within the index buffer. - * \param vertexOffset value added to vertex index before indexing into the - * vertex buffer. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 indexCount, - Uint32 instanceCount, - Uint32 firstIndex, - Sint32 vertexOffset, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); /** * Draws data using bound graphics state. * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param vertexCount the number of vertices to draw. - * \param instanceCount the number of instances that will be drawn. - * \param firstVertex the index of the first vertex to draw. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 vertexCount, - Uint32 instanceCount, - Uint32 firstVertex, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); /** * Draws data using bound graphics state and with draw parameters set from a * buffer. * - * The buffer layout should match the layout of SDL_GPUIndirectDrawCommand. - * You must not call this function before binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Draws data using bound graphics state with an index buffer enabled and with * draw parameters set from a buffer. * - * The buffer layout should match the layout of - * SDL_GPUIndexedIndirectDrawCommand. You must not call this function before - * binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Ends the given render pass. @@ -1890,12 +3199,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( * All bound graphics state on the render pass command buffer is unset. The * render pass handle is now invalid. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( - SDL_GPURenderPass *renderPass); + SDL_GPURenderPass *render_pass); /* Compute Pass */ @@ -1903,89 +3212,115 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( * Begins a compute pass on a command buffer. * * A compute pass is defined by a set of texture subresources and buffers that - * will be written to by compute pipelines. These textures and buffers must - * have been created with the COMPUTE_STORAGE_WRITE bit. All operations - * related to compute pipelines must take place inside of a compute pass. You - * must not begin another compute pass, or a render pass or copy pass before - * ending the compute pass. + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. * - * A VERY IMPORTANT NOTE Textures and buffers bound as write-only MUST NOT be - * read from during the compute pass. Doing so will result in undefined - * behavior. If your compute work requires reading the output from a previous - * dispatch, you MUST end the current compute pass and begin a new one before - * you can safely access the data. + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! * - * \param commandBuffer a command buffer. - * \param storageTextureBindings an array of writeable storage texture binding - * structs. - * \param storageTextureBindingCount the number of storage textures to bind - * from the array. - * \param storageBufferBindings an array of writeable storage buffer binding - * structs. - * \param storageBufferBindingCount the number of storage buffers to bind from - * the array. + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. * \returns a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPUComputePass */ extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUStorageTextureWriteOnlyBinding *storageTextureBindings, - Uint32 storageTextureBindingCount, - SDL_GPUStorageBufferWriteOnlyBinding *storageBufferBindings, - Uint32 storageBufferBindingCount); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); /** * Binds a compute pipeline on a command buffer for use in compute dispatch. * - * \param computePass a compute pass handle. - * \param computePipeline a compute pipeline to bind. + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( - SDL_GPUComputePass *computePass, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler bindings to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures as readonly for use on the compute pipeline. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers as readonly for use on the compute pipeline. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffer binding structs. - * \param bindingCount the number of storage buffers to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffer binding structs. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Dispatches compute work. @@ -1997,21 +3332,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. - * \param groupCountX number of local workgroups to dispatch in the X - * dimension. - * \param groupCountY number of local workgroups to dispatch in the Y - * dimension. - * \param groupCountZ number of local workgroups to dispatch in the Z - * dimension. + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( - SDL_GPUComputePass *computePass, - Uint32 groupCountX, - Uint32 groupCountY, - Uint32 groupCountZ); + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); /** * Dispatches compute work with parameters set from a buffer. @@ -2025,16 +3360,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * \param buffer a buffer containing dispatch parameters. - * \param offsetInBytes the offset to start reading from the dispatch buffer. + * \param offset the offset to start reading from the dispatch buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( - SDL_GPUComputePass *computePass, + SDL_GPUComputePass *compute_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes); + Uint32 offset); /** * Ends the current compute pass. @@ -2042,12 +3377,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( * All bound compute state on the command buffer is unset. The compute pass * handle is now invalid. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( - SDL_GPUComputePass *computePass); + SDL_GPUComputePass *compute_pass); /* TransferBuffer Data */ @@ -2057,28 +3392,29 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( * You must unmap the transfer buffer before encoding upload commands. * * \param device a GPU context. - * \param transferBuffer a transfer buffer. - * \param cycle if SDL_TRUE, cycles the transfer buffer if it is bound. - * \returns the address of the mapped transfer buffer memory. + * \param transfer_buffer a transfer buffer. + * \param cycle if true, cycles the transfer buffer if it is already bound. + * \returns the address of the mapped transfer buffer memory, or NULL on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer, - SDL_bool cycle); + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); /** * Unmaps a previously mapped transfer buffer. * * \param device a GPU context. - * \param transferBuffer a previously mapped transfer buffer. + * \param transfer_buffer a previously mapped transfer buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /* Copy Pass */ @@ -2089,13 +3425,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( * inside a copy pass. You must not begin another copy pass, or a render pass * or compute pass before ending the copy pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \returns a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /** * Uploads data from a transfer buffer to a texture. @@ -2106,21 +3442,19 @@ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( * You must align the data in the transfer buffer to a multiple of the texel * size of the texture format. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with image layout information. * \param destination the destination texture region. - * \param cycle if SDL_TRUE, cycles the texture if the texture is bound, - * otherwise overwrites the data. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureTransferInfo *source, - SDL_GPUTextureRegion *destination, - SDL_bool cycle); - -/* Uploads data from a TransferBuffer to a Buffer. */ + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); /** * Uploads data from a transfer buffer to a buffer. @@ -2128,19 +3462,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( * The upload occurs on the GPU timeline. You may assume that the upload has * finished in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with offset. * \param destination the destination buffer with offset and size. - * \param cycle if SDL_TRUE, cycles the buffer if it is bound, otherwise + * \param cycle if true, cycles the buffer if it is already bound, otherwise * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUTransferBufferLocation *source, - SDL_GPUBufferRegion *destination, - SDL_bool cycle); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); /** * Performs a texture-to-texture copy. @@ -2148,27 +3482,25 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source a source texture region. * \param destination a destination texture region. * \param w the width of the region to copy. * \param h the height of the region to copy. * \param d the depth of the region to copy. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination + * \param cycle if true, cycles the destination texture if the destination * texture is bound, otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureLocation *source, - SDL_GPUTextureLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, Uint32 w, Uint32 h, Uint32 d, - SDL_bool cycle); - -/* Copies data from a buffer to a buffer. */ + bool cycle); /** * Performs a buffer-to-buffer copy. @@ -2176,21 +3508,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the buffer and offset to copy from. * \param destination the buffer and offset to copy to. * \param size the length of the buffer to copy. - * \param cycle if SDL_TRUE, cycles the destination buffer if it is bound, + * \param cycle if true, cycles the destination buffer if it is already bound, * otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferLocation *source, - SDL_GPUBufferLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, Uint32 size, - SDL_bool cycle); + bool cycle); /** * Copies data from a texture to a transfer buffer on the GPU timeline. @@ -2198,17 +3530,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source texture region. * \param destination the destination transfer buffer with image layout * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureRegion *source, - SDL_GPUTextureTransferInfo *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); /** * Copies data from a buffer to a transfer buffer on the GPU timeline. @@ -2216,39 +3548,39 @@ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source buffer with offset and size. * \param destination the destination transfer buffer with offset. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferRegion *source, - SDL_GPUTransferBufferLocation *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); /** * Ends the current copy pass. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( - SDL_GPUCopyPass *copyPass); + SDL_GPUCopyPass *copy_pass); /** * Generates mipmaps for the given texture. * * This function must not be called inside of any pass. * - * \param commandBuffer a commandBuffer. + * \param command_buffer a command_buffer. * \param texture a texture with more than 1 mip level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, SDL_GPUTexture *texture); /** @@ -2256,23 +3588,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( * * This function must not be called inside of any pass. * - * \param commandBuffer a command buffer. - * \param source the texture region to copy from. - * \param destination the texture region to copy to. - * \param flipMode the flip mode for the source texture region. - * \param filterMode the filter mode that will be used when blitting. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination - * texture is bound, otherwise overwrites the data. + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUBlitRegion *source, - SDL_GPUBlitRegion *destination, - SDL_FlipMode flipMode, - SDL_GPUFilter filterMode, - SDL_bool cycle); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); /* Submission/Presentation */ @@ -2283,17 +3606,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( * * \param device a GPU context. * \param window an SDL_Window. - * \param swapchainComposition the swapchain composition to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition); + SDL_GPUSwapchainComposition swapchain_composition); /** * Determines whether a presentation mode is supported by the window. @@ -2302,40 +3625,46 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( * * \param device a GPU context. * \param window an SDL_Window. - * \param presentMode the presentation mode to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUPresentMode presentMode); + SDL_GPUPresentMode present_mode); /** * Claims a window, creating a swapchain structure for it. * * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created * the window. * * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain - * parameters, you must call SetSwapchainParameters after claiming the window. + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. * * \param device a GPU context. * \param window an SDL_Window. - * \returns SDL_TRUE on success, otherwise SDL_FALSE. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. * - * \sa SDL_AcquireGPUSwapchainTexture + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_ReleaseWindowFromGPUDevice * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( SDL_GPUDevice *device, SDL_Window *window); @@ -2345,7 +3674,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( * \param device a GPU context. * \param window an SDL_Window that has been claimed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ @@ -2366,29 +3695,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( * * \param device a GPU context. * \param window an SDL_Window that has been claimed. - * \param swapchainComposition the desired composition of the swapchain. - * \param presentMode the desired present mode for the swapchain. - * \returns SDL_TRUE if successful, SDL_FALSE on error. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGPUSwapchainParameters( +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition, - SDL_GPUPresentMode presentMode); + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture pointer with NULL, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight( + SDL_GPUDevice *device, + Uint32 allowed_frames_in_flight); /** * Obtains the texture format of the swapchain for the given window. * + * Note that this format can change if the swapchain parameters change. + * * \param device a GPU context. * \param window an SDL_Window that has been claimed. * \returns the texture format of the swapchain. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( SDL_GPUDevice *device, @@ -2400,28 +3761,118 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma * When a swapchain texture is acquired on a command buffer, it will * automatically be submitted for presentation when the command buffer is * submitted. The swapchain texture should only be referenced by the command - * buffer used to acquire it. May return NULL under certain conditions. This - * is not necessarily an error. This texture is managed by the implementation - * and must not be freed by the user. You MUST NOT call this function from any - * thread other than the one that created the window. + * buffer used to acquire it. * - * \param commandBuffer a command buffer. + * This function will fill the swapchain texture handle with NULL if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. * \param window a window that has been claimed. - * \param pWidth a pointer filled in with the swapchain width. - * \param pHeight a pointer filled in with the swapchain height. - * \returns a swapchain texture. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight */ -extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( - SDL_GPUCommandBuffer *commandBuffer, +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, SDL_Window *window, - Uint32 *pWidth, - Uint32 *pHeight); + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with NULL in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the pointer is NULL before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); /** * Submits a command buffer so its commands can be processed on the GPU. @@ -2433,16 +3884,19 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( - SDL_GPUCommandBuffer *commandBuffer); +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Submits a command buffer so its commands can be processed on the GPU, and @@ -2456,63 +3910,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. - * \returns a fence associated with the command buffer. + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_ReleaseGPUFence */ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); + +/** + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Blocks the thread until the GPU is completely idle. * * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitForGPUFences */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUIdle( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( SDL_GPUDevice *device); /** * Blocks the thread until the given fences are signaled. * * \param device a GPU context. - * \param waitAll if 0, wait for any fence to be signaled, if 1, wait for all - * fences to be signaled. - * \param pFences an array of fences to wait on. - * \param fenceCount the number of fences in the pFences array. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence * \sa SDL_WaitForGPUIdle */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUFences( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( SDL_GPUDevice *device, - SDL_bool waitAll, - SDL_GPUFence **pFences, - Uint32 fenceCount); + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); /** * Checks the status of a fence. * * \param device a GPU context. * \param fence a fence. - * \returns SDL_TRUE if the fence is signaled, SDL_FALSE if it is not. + * \returns true if the fence is signaled, false if it is not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( SDL_GPUDevice *device, SDL_GPUFence *fence); @@ -2522,7 +4007,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( * \param device a GPU context. * \param fence a fence. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ @@ -2535,15 +4020,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( /** * Obtains the texel block size for a texture format. * - * \param textureFormat the texture format you want to know the texel size of. + * \param format the texture format you want to know the texel size of. * \returns the texel block size of the texture format. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( - SDL_GPUTextureFormat textureFormat); + SDL_GPUTextureFormat format); /** * Determines whether a texture format is supported for a given type and @@ -2555,9 +4040,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( * \param usage a bitmask of all usage scenarios to check. * \returns whether the texture format is supported for this type and usage. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( SDL_GPUDevice *device, SDL_GPUTextureFormat format, SDL_GPUTextureType type, @@ -2568,15 +4053,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( * * \param device a GPU context. * \param format the texture format to check. - * \param sampleCount the sample count to check. + * \param sample_count the sample count to check. * \returns a hardware-specific version of min(preferred, possible). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( SDL_GPUDevice *device, SDL_GPUTextureFormat format, - SDL_GPUSampleCount sampleCount); + SDL_GPUSampleCount sample_count); + +/** + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize( + SDL_GPUTextureFormat format, + Uint32 width, + Uint32 height, + Uint32 depth_or_layer_count); #ifdef SDL_PLATFORM_GDK @@ -2589,7 +4091,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -2604,7 +4106,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_guid.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_guid.h index 285b237..e2f32ff 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_guid.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_guid.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,13 +26,14 @@ * * A GUID is a 128-bit value that represents something that is uniquely * identifiable by this value: "globally unique." + * + * SDL provides functions to convert a GUID to/from a string. */ #ifndef SDL_guid_h_ #define SDL_guid_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -55,7 +56,7 @@ extern "C" { * GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs on different operating systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GUID { Uint8 data[16]; @@ -70,7 +71,7 @@ typedef struct SDL_GUID { * \param pszGUID buffer in which to write the ASCII string. * \param cbGUID the size of pszGUID, should be at least 33 bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StringToGUID */ @@ -86,7 +87,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_GUID structure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_haptic.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_haptic.h index 95446fe..a45335b 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_haptic.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_haptic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -66,7 +66,7 @@ * Complete example: * * ```c - * SDL_bool test_haptic(SDL_Joystick *joystick) + * bool test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -74,12 +74,12 @@ * * // Open the device * haptic = SDL_OpenHapticFromJoystick(joystick); - * if (haptic == NULL) return SDL_FALSE; // Most likely joystick isn't haptic + * if (haptic == NULL) return false; // Most likely joystick isn't haptic * * // See if it can do sine waves * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) { * SDL_CloseHaptic(haptic); // No sine effect - * return SDL_FALSE; + * return false; * } * * // Create the effect @@ -106,7 +106,7 @@ * // Close the device * SDL_CloseHaptic(haptic); * - * return SDL_TRUE; // Success + * return true; // Success * } * ``` * @@ -139,15 +139,14 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_OpenHaptic - * \sa SDL_OpenHapticFromJoystick - * \sa SDL_CloseHaptic + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct SDL_Haptic; typedef struct SDL_Haptic SDL_Haptic; @@ -168,7 +167,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Constant haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -179,7 +178,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates sine waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -190,7 +189,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates square waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -201,7 +200,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates triangular waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -212,7 +211,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth up waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -223,7 +222,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth down waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -234,7 +233,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Ramp haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticRamp */ @@ -246,7 +245,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates a spring. Effect is based on the * axes position. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -258,7 +257,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -270,7 +269,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -282,7 +281,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates friction. Effect is based on the * axes movement. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -293,19 +292,31 @@ typedef struct SDL_Haptic SDL_Haptic; * * Haptic effect for direct control over high/low frequency motors. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** @@ -313,7 +324,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * User defined custom haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_CUSTOM (1u<<15) @@ -326,7 +337,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting the global gain. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticGain */ @@ -337,7 +348,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting autocenter. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticAutocenter */ @@ -348,7 +359,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports querying effect status. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus */ @@ -359,7 +370,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Devices supports being paused. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_PauseHaptic * \sa SDL_ResumeHaptic @@ -375,7 +386,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses polar coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -384,7 +395,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses cartesian coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -393,7 +404,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses spherical coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -405,7 +416,7 @@ typedef struct SDL_Haptic SDL_Haptic; * This provides better compatibility across platforms and devices as SDL will * guess the correct axis. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -422,7 +433,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Used to play a device an infinite number of times. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect */ @@ -523,7 +534,7 @@ typedef struct SDL_Haptic SDL_Haptic; * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN @@ -547,7 +558,7 @@ typedef struct SDL_HapticDirection * A constant effect applies a constant force in the specified direction to * the joystick. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect @@ -629,7 +640,7 @@ typedef struct SDL_HapticConstant * \| \| \| \| \| \| \| * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE @@ -685,7 +696,7 @@ typedef struct SDL_HapticPeriodic * SDL_HapticDirection diagram for which side is positive and which is * negative. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticDirection * \sa SDL_HAPTIC_SPRING @@ -699,7 +710,7 @@ typedef struct SDL_HapticCondition /* Header */ Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -728,7 +739,7 @@ typedef struct SDL_HapticCondition * effects get added to the ramp effect making the effect become quadratic * instead of linear. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect @@ -767,7 +778,7 @@ typedef struct SDL_HapticRamp * motors, commonly found in modern game controllers. The small (right) motor * is high frequency, and the large (left) motor is low frequency. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HapticEffect @@ -797,7 +808,7 @@ typedef struct SDL_HapticLeftRight * If channels is one, the effect is rotated using the defined direction. * Otherwise it uses the samples in data for the different axes. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CUSTOM * \sa SDL_HapticEffect @@ -892,7 +903,7 @@ typedef struct SDL_HapticCustom * Note either the attack_level or the fade_level may be above the actual * effect level. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic @@ -921,7 +932,7 @@ typedef union SDL_HapticEffect * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_HapticID; @@ -937,7 +948,7 @@ typedef Uint32 SDL_HapticID; * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -953,7 +964,7 @@ extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticName * \sa SDL_OpenHaptic @@ -974,7 +985,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID ins * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_GetHaptics @@ -993,7 +1004,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id); @@ -1004,7 +1015,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instan * \returns the instance ID of the specified haptic device on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); @@ -1016,7 +1027,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticNameForID */ @@ -1025,13 +1036,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromMouse */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -1039,7 +1050,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); * \returns the haptic device identifier or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsMouseHaptic @@ -1050,13 +1061,13 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. + * \returns true if the joystick is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -1073,7 +1084,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick * \returns a valid haptic device identifier on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsJoystickHaptic @@ -1085,7 +1096,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick * * \param haptic the SDL_Haptic device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -1102,7 +1113,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic); * \returns the number of effects the haptic device can store or a negative * error code on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffectsPlaying * \sa SDL_GetHapticFeatures @@ -1118,7 +1129,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); * \returns the number of effects the haptic device can play at the same time * or -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffects * \sa SDL_GetHapticFeatures @@ -1132,7 +1143,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HapticEffectSupported * \sa SDL_GetMaxHapticEffects @@ -1149,7 +1160,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); * \returns the number of axes on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); @@ -1158,14 +1169,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1176,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti * \returns the ID of the effect on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyHapticEffect * \sa SDL_RunHapticEffect @@ -1196,15 +1207,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_RunHapticEffect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1219,31 +1230,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus * \sa SDL_StopHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1254,7 +1265,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, in * \param haptic the SDL_Haptic device to destroy the effect on. * \param effect the ID of the haptic effect to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect */ @@ -1267,14 +1278,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns SDL_TRUE if it is playing, SDL_FALSE if it isn't playing or haptic - * status isn't supported. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1289,14 +1300,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *hapti * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1308,14 +1319,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int g * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. @@ -1327,14 +1338,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** * Resume a haptic device. @@ -1342,55 +1353,55 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1398,28 +1409,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble * \sa SDL_StopHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hidapi.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hidapi.h index 66bea9d..131b037 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hidapi.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hidapi.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -65,14 +65,14 @@ extern "C" { /** * An opaque handle representing an open HID device. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device SDL_hid_device; /** * HID underlying bus types. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_hid_bus_type { /** Unknown bus type */ @@ -107,7 +107,7 @@ typedef enum SDL_hid_bus_type { /** * Information about a connected HID device * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device_info { @@ -169,7 +169,7 @@ typedef struct SDL_hid_device_info * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_exit */ @@ -184,7 +184,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_init */ @@ -205,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void); * \returns a change counter that is incremented with each potential device * change, or 0 if device change detection isn't available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_enumerate */ @@ -233,7 +233,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); * in the case of failure. Free this linked list by calling * SDL_hid_free_enumeration(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_device_change_count */ @@ -247,7 +247,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho * \param devs pointer to a list of struct_device returned from * SDL_hid_enumerate(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); @@ -265,7 +265,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); @@ -279,7 +279,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_ * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); @@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path) * \returns the actual number of bytes written and -1 on on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne * SDL_GetError() for more information. If no packet was available to * be read within the timeout period, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); @@ -348,7 +348,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign * be read and the handle is in non-blocking mode, this function * returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -367,7 +367,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); @@ -392,7 +392,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int * \returns the actual number of bytes written and -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -415,7 +415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -438,7 +438,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -449,7 +449,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); @@ -462,7 +462,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device * * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -488,7 +488,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -502,7 +502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); @@ -514,7 +514,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, * on failure; call SDL_GetError() for more information. This struct * is valid until the device is closed with SDL_hid_close(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); @@ -530,18 +530,18 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi * \returns the number of bytes actually copied or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. + * \param active true to start the scan, false to stop the scan. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hints.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hints.h index 8433240..8f2d074 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hints.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_hints.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,8 +22,6 @@ /** * # CategoryHints * - * Official documentation for SDL configuration variables - * * This file contains functions to set and get configuration hints, as well as * listing each of them alphabetically. * @@ -63,7 +61,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" @@ -83,7 +81,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" @@ -98,10 +96,27 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" +/** + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" + /** * A variable to control whether we trap the Android back button to handle it * manually. @@ -121,7 +136,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" @@ -137,7 +152,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_ID "SDL_APP_ID" @@ -155,7 +170,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_NAME "SDL_APP_NAME" @@ -178,7 +193,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" @@ -193,7 +208,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" @@ -201,16 +216,58 @@ extern "C" { * Specify the default ALSA audio device name. * * This variable is a specific audio device to open when the "default" audio - * device is used. By default if 4 channel audio is requested, the - * "plug:surround40" device will be opened and if 6 channel audio is requested - * the "plug:surround51" device will be opened. + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE */ #define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" +/** + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" + +/** + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" + /** * A variable controlling the audio category on iOS and macOS. * @@ -225,7 +282,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" @@ -238,7 +295,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" @@ -261,7 +318,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" @@ -283,7 +340,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" @@ -310,7 +367,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" @@ -336,7 +393,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" @@ -347,7 +404,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" @@ -358,7 +415,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" @@ -371,7 +428,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" @@ -385,7 +442,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" @@ -398,7 +455,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" @@ -409,18 +466,23 @@ extern "C" { * device, this hint can be used to specify a default format that will be * used. * - * The variable can be set to the following values: - "U8": Unsigned 8-bit - * audio - "S8": Signed 8-bit audio - "S16LE": Signed 16-bit little-endian - * audio - "S16BE": Signed 16-bit big-endian audio - "S16": Signed 16-bit - * native-endian audio (default) - "S32LE": Signed 32-bit little-endian audio - * - "S32BE": Signed 32-bit big-endian audio - "S32": Signed 32-bit - * native-endian audio - "F32LE": Floating point little-endian audio - - * "F32BE": Floating point big-endian audio - "F32": Floating point - * native-endian audio + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" @@ -433,7 +495,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" @@ -456,7 +518,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" @@ -471,7 +533,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" @@ -486,7 +548,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" @@ -509,7 +571,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" @@ -525,7 +587,7 @@ extern "C" { * best camera backend on your behalf. This hint needs to be set before * SDL_Init() is called to be useful. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" @@ -558,7 +620,7 @@ extern "C" { * * The items can be prefixed by '+'/'-' to add/remove features. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" @@ -572,7 +634,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" @@ -601,7 +663,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" @@ -619,7 +681,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" @@ -640,7 +702,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" @@ -653,7 +715,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" @@ -668,12 +730,13 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all * - any other string without a leading # sign applies to the element on the * page with that ID. * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" @@ -690,7 +753,7 @@ extern "C" { * * This hint must be set before SDL_StartTextInput() is called * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" @@ -707,7 +770,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" @@ -731,7 +794,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" @@ -751,7 +814,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" @@ -772,7 +835,7 @@ extern "C" { * * This hint should be set before calling SDL_GetWindowSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" @@ -787,7 +850,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" @@ -803,7 +866,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" @@ -827,7 +890,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" @@ -845,7 +908,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" @@ -863,7 +926,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" @@ -886,7 +949,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" @@ -898,7 +961,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" @@ -910,7 +973,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" @@ -925,7 +988,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" @@ -941,7 +1004,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" @@ -952,7 +1015,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" @@ -970,7 +1033,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" @@ -988,7 +1051,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" @@ -1002,7 +1065,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" @@ -1011,12 +1074,12 @@ extern "C" { * * By default, SDL will try all available GPU backends in a reasonable order * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "d3d11" if, say, your hardware supports - * D3D12 but want to try using D3D11 instead. + * force a specific target, such as "direct3d11" if, say, your hardware + * supports D3D12 but want to try using D3D11 instead. * - * This hint should be set before SDL_GPUSelectBackend() is called. + * This hint should be set before any GPU functions are called. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" @@ -1035,7 +1098,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" @@ -1052,7 +1115,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" @@ -1075,7 +1138,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" @@ -1094,7 +1157,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" @@ -1111,7 +1174,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" @@ -1128,7 +1191,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" @@ -1149,7 +1212,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" @@ -1167,7 +1230,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" @@ -1188,7 +1251,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" @@ -1198,10 +1261,35 @@ extern "C" { * * This variable is currently only used by the Linux joystick driver. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" +/** + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" + /** * A variable containing a list of flightstick style controllers. * @@ -1215,7 +1303,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" @@ -1236,7 +1324,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" @@ -1246,12 +1334,14 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": GameInput is not used. (default) + * - "0": GameInput is not used. * - "1": GameInput is used. * + * The default is "1" on GDK platforms, and "0" otherwise. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" @@ -1269,7 +1359,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" @@ -1290,7 +1380,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" @@ -1305,9 +1395,9 @@ extern "C" { * This variable is the default for all drivers, but can be overridden by the * hints for specific drivers below. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" @@ -1322,9 +1412,9 @@ extern "C" { * - "1": Left and right Joy-Con controllers will be combined into a single * controller. (default) * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" @@ -1339,9 +1429,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" @@ -1362,7 +1452,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" @@ -1377,9 +1467,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" @@ -1398,7 +1488,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" @@ -1413,9 +1503,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" @@ -1430,9 +1520,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" @@ -1452,9 +1542,9 @@ extern "C" { * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" @@ -1469,9 +1559,9 @@ extern "C" { * * The default value is 0. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" @@ -1486,9 +1576,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" @@ -1503,36 +1593,10 @@ extern "C" { * This hint can be set anytime, but only takes effect when extended input * reports are enabled. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" -/** - * A variable controlling whether extended input reports should be used for - * PS4 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports are enabled. - * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value will also control - * the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for PS5 controllers should * be used. @@ -1544,9 +1608,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" @@ -1559,35 +1623,10 @@ extern "C" { * - "0": player LEDs are not enabled. * - "1": player LEDs are enabled. (default) * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" -/** - * A variable controlling whether extended input reports should be used for - * PS5 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports. - * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value defaults to the - * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD * controllers should be used. @@ -1599,9 +1638,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" @@ -1616,7 +1655,7 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" @@ -1631,12 +1670,31 @@ extern "C" { * Bluetooth access and may prompt the user for permission on iOS and * Android. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" +/** + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" + /** * A variable controlling whether the HIDAPI driver for the Steam Deck builtin * controller should be used. @@ -1648,12 +1706,23 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + /** * A variable controlling whether the HIDAPI driver for Nintendo Switch * controllers should be used. @@ -1665,9 +1734,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" @@ -1686,7 +1755,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" @@ -1701,7 +1770,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" @@ -1717,7 +1786,7 @@ extern "C" { * * This hint should be set before opening a Joy-Con controller. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" @@ -1730,12 +1799,12 @@ extern "C" { * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. + * This driver doesn't work with the dolphinbar, so the default is false for + * now. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" @@ -1750,7 +1819,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" @@ -1766,9 +1835,9 @@ extern "C" { * The default is "0" on Windows, otherwise the value of * SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" @@ -1783,9 +1852,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" @@ -1800,7 +1869,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" @@ -1815,9 +1884,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" @@ -1832,9 +1901,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" @@ -1853,7 +1922,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" @@ -1868,7 +1937,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" @@ -1883,7 +1952,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" @@ -1898,7 +1967,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" @@ -1916,7 +1985,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" @@ -1932,7 +2001,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" @@ -1947,7 +2016,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" @@ -1962,7 +2031,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" @@ -1979,7 +2048,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" @@ -1994,7 +2063,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" @@ -2004,12 +2073,12 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": A separate thread is not used. (default) - * - "1": A separate thread is used for handling raw input messages. + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" @@ -2026,7 +2095,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" @@ -2047,7 +2116,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" @@ -2062,7 +2131,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" @@ -2079,7 +2148,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" @@ -2100,7 +2169,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" @@ -2118,7 +2187,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" @@ -2139,7 +2208,7 @@ extern "C" { * - "latin_letters": For keyboards using non-Latin letters, such as Russian * or Thai, the letter keys generate keycodes as though it had an en_US * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian - * keyboard would yield 'a' instead of 'ф'. + * keyboard would yield 'a' instead of a Cyrillic letter. * * The default value for this hint is "french_numbers,latin_letters" * @@ -2152,7 +2221,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" @@ -2166,7 +2235,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" @@ -2194,7 +2263,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" @@ -2220,7 +2289,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_LOGGING "SDL_LOGGING" @@ -2234,9 +2303,9 @@ extern "C" { * (default) * - "1": The application may remain in the background when launched. * - * This hint should be set before applicationDidFinishLaunching() is called. + * This hint needs to be set before SDL_Init(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" @@ -2252,7 +2321,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" @@ -2275,25 +2344,73 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" +/** + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + +/** + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" + /** * Request SDL_AppIterate() be called at a specific rate. * - * This number is in Hz, so "60" means try to iterate 60 times per second. + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. * * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, * this hint is ignored. When the hint can be used, it is allowed to be * changed at any time. * - * This defaults to 60, and specifying NULL for the hint's value will restore + * This defaults to 0, and specifying NULL for the hint's value will restore * the default. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" @@ -2312,7 +2429,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" @@ -2321,7 +2438,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" @@ -2330,10 +2447,22 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" +/** + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" + /** * A variable controlling whether warping a hidden mouse cursor will activate * relative mouse mode. @@ -2362,7 +2491,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" @@ -2376,7 +2505,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" @@ -2386,7 +2515,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" @@ -2407,32 +2536,17 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" -/** - * A variable controlling whether relative mouse mode is implemented using - * mouse warping. - * - * The variable can be set to the following values: - * - * - "0": Relative mouse mode uses raw input. (default) - * - "1": Relative mouse mode uses mouse warping. - * - * This hint can be set anytime relative mode is not currently enabled. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" - /** * A variable setting the scale for mouse motion, in floating point, when the * mouse is in relative mode. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" @@ -2446,12 +2560,12 @@ extern "C" { * - "1": Relative mouse motion will be scaled using the system mouse * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after * system speed scale. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" @@ -2470,7 +2584,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" @@ -2478,9 +2592,10 @@ extern "C" { * A variable controlling whether the hardware cursor stays visible when * relative mode is active. * - * This variable can be set to the following values: "0" - The cursor will be - * hidden while relative mode is active (default) "1" - The cursor will remain - * visible while relative mode is active + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active * * Note that for systems without raw hardware inputs, relative mode is * implemented using warping, so the hardware cursor will visibly warp between @@ -2488,27 +2603,10 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" -/** - * Controls how often SDL issues cursor confinement commands to the operating - * system while relative mode is active, in case the desired confinement state - * became out-of-sync due to interference from other running programs. - * - * The variable can be integers representing miliseconds between each refresh. - * A value of zero means SDL will not automatically refresh the confinement. - * The default value varies depending on the operating system, this variable - * might not have any effects on inapplicable platforms such as those without - * a cursor. - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" - /** * A variable controlling whether mouse events should generate synthetic touch * events. @@ -2522,7 +2620,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" @@ -2540,7 +2638,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" @@ -2555,7 +2653,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" @@ -2563,12 +2661,25 @@ extern "C" { * Specify the OpenGL library to load. * * This hint should be set before creating an OpenGL window or creating an - * OpenGL context. + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" +/** + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" + /** * A variable controlling what driver to use for OpenGL ES contexts. * @@ -2599,10 +2710,22 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" + /** * A variable controlling which orientations are allowed on iOS/Android. * @@ -2618,7 +2741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" @@ -2638,7 +2761,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" @@ -2656,7 +2779,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" @@ -2673,9 +2796,13 @@ extern "C" { * - "1": SDL will send a quit event when the last window is requesting to * close. (default) * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" @@ -2690,7 +2817,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" @@ -2706,7 +2833,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" @@ -2720,7 +2847,7 @@ extern "C" { * * By default, SDL does not use Vulkan Validation Layers. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" @@ -2734,7 +2861,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" @@ -2749,7 +2876,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" @@ -2758,7 +2885,7 @@ extern "C" { * * If the application doesn't pick a specific renderer to use, this variable * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * can't be initialized, creating a renderer will fail. * * This variable is case insensitive and can be set to the following values: * @@ -2770,14 +2897,19 @@ extern "C" { * - "opengles" * - "metal" * - "vulkan" + * - "gpu" * - "software" * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * * The default varies by platform, but it's the first one in the list that is * available on the current platform. * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" @@ -2795,7 +2927,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" @@ -2810,7 +2942,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" @@ -2827,7 +2959,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" @@ -2844,7 +2976,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" @@ -2861,7 +2993,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. * * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED */ @@ -2883,7 +3015,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" @@ -2895,7 +3027,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" @@ -2917,7 +3049,7 @@ extern "C" { * * This hint should be set before calling SDL_DisableScreenSaver() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" @@ -2936,7 +3068,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" @@ -2950,7 +3082,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" @@ -2964,7 +3096,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" @@ -2991,32 +3123,32 @@ extern "C" { * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling * policy * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** * A string specifying additional information to use with - * SDL_SetThreadPriority. + * SDL_SetCurrentThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. * * pthread hint values are "current", "other", "fifo" and "rr". Currently no * other platform hint values are defined but may be in the future. * * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the * distro configured execution budget for rtkit. This budget can be queried - * through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" @@ -3036,7 +3168,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" @@ -3051,7 +3183,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" @@ -3072,7 +3204,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -3087,7 +3219,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" @@ -3101,10 +3233,35 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" +/** + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" + /** * Tell the video driver that we only want a double buffer. * @@ -3124,7 +3281,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" @@ -3136,9 +3293,13 @@ extern "C" { * force a specific target, such as "x11" if, say, you are on Wayland but want * to try talking to the X server instead. * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" @@ -3151,7 +3312,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" @@ -3165,7 +3326,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" @@ -3181,7 +3342,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" @@ -3199,10 +3360,31 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + /** * A variable controlling whether fullscreen windows are minimized when they * lose focus. @@ -3215,7 +3397,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" @@ -3232,7 +3414,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" @@ -3258,7 +3440,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" @@ -3276,7 +3458,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" @@ -3296,7 +3478,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" @@ -3318,7 +3500,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" @@ -3338,7 +3520,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" @@ -3357,6 +3539,8 @@ extern "C" { * * - Rounding errors can result with odd window sizes and/or desktop scales, * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. * - The window may be unusably small on scaled desktops. * - The window may jump in size when moving between displays of different * scale factors. @@ -3375,7 +3559,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" @@ -3397,7 +3581,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" @@ -3412,7 +3596,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" @@ -3431,7 +3615,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" @@ -3445,7 +3629,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" @@ -3456,7 +3640,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" @@ -3465,7 +3649,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" @@ -3474,7 +3658,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" @@ -3488,7 +3672,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" @@ -3503,7 +3687,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" @@ -3518,7 +3702,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" @@ -3529,7 +3713,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" @@ -3542,7 +3726,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" @@ -3557,7 +3741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" @@ -3572,7 +3756,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" @@ -3588,7 +3772,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" @@ -3599,7 +3783,7 @@ extern "C" { * * This hint should be set before calling SDL_Vulkan_CreateSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" @@ -3609,7 +3793,7 @@ extern "C" { * This hint should be set before creating a Vulkan window or calling * SDL_Vulkan_LoadLibrary(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" @@ -3641,7 +3825,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" @@ -3653,7 +3837,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" @@ -3681,7 +3865,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" @@ -3701,7 +3885,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" @@ -3718,7 +3902,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" @@ -3735,7 +3919,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" @@ -3753,7 +3937,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" @@ -3769,7 +3953,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" @@ -3785,7 +3969,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" @@ -3814,7 +3998,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" @@ -3829,7 +4013,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" @@ -3845,7 +4029,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" @@ -3859,7 +4043,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" @@ -3880,7 +4064,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" @@ -3890,9 +4074,18 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** @@ -3917,7 +4110,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" @@ -3934,123 +4127,10 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" -/** - * A variable controlling whether back-button-press events on Windows Phone to - * be marked as handled. - * - * Windows Phone devices typically feature a Back button. When pressed, the OS - * will emit back-button-press events, which apps are expected to handle in an - * appropriate manner. If apps do not explicitly mark these events as - * 'Handled', then the OS will invoke its default behavior for unhandled - * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate - * the app (and attempt to switch to the previous app, or to the device's home - * screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to - * mark back-button-press events as Handled, if and when one is sent to the - * app. - * - * Internally, Windows Phone sends back button events as parameters to special - * back-button-press callback functions. Apps that need to respond to - * back-button-press events are expected to register one or more callback - * functions for such, shortly after being launched (during the app's - * initialization phase). After the back button is pressed, the OS will invoke - * these callbacks. If the app's callback(s) do not explicitly mark the event - * as handled by the time they return, or if the app never registers one of - * these callback, the OS will consider the event un-handled, and it will - * apply its default back button behavior (terminate the app). - * - * SDL registers its own back-button-press callback with the Windows Phone OS. - * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN - * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after - * which it will check the contents of the hint, - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the - * back button event's Handled property will get set to 'true'. If the hint's - * value is set to something else, or if it is unset, SDL will leave the - * event's Handled property alone. (By default, the OS sets this property to - * 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for - * either event type is suitable.) Any value of - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied - * to the OS' current back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found at - * the following page, on Microsoft's developer site: - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** - * A variable specifying the label text for a WinRT app's privacy policy link. - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, - * 8.1, and RT, Microsoft mandates that this policy be available via the - * Windows Settings charm. SDL provides code to add a link there, with its - * label text being set via the optional hint, - * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A - * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the - * actual text of the policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". - * - * For additional information on linking to a privacy policy, see the - * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. - * - * This hint should be set before SDL is initialized. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A variable specifying the URL to a WinRT app's privacy policy. - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - /** * A variable controlling whether X11 windows are marked as override-redirect. * @@ -4068,7 +4148,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" @@ -4085,18 +4165,18 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** * Specify the XCB library to load for the X11 driver. * - * This defaults to "libX11-xcb.so" + * The default is platform-specific, often "libX11-xcb.so.1". * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" @@ -4111,7 +4191,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" @@ -4135,15 +4215,45 @@ extern "C" { * This hint should be set before an assertion failure is triggered and can be * changed at any time. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ASSERT "SDL_ASSERT" +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + /** * An enumeration of hint priorities. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_HintPriority { @@ -4162,18 +4272,18 @@ typedef enum SDL_HintPriority * \param name the hint to set. * \param value the value of the hint variable. * \param priority the SDL_HintPriority level for the hint. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); /** * Set a hint with normal priority. @@ -4184,18 +4294,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, c * * \param name the hint to set. * \param value the value of the hint variable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); /** * Reset a hint to the default value. @@ -4205,17 +4315,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *v * change. * * \param name the hint to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_ResetHints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); /** * Reset all hints to the default values. @@ -4226,7 +4336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetHint */ @@ -4245,7 +4355,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); * callback instead is always thread-safe, as SDL holds a lock * on the thread subsystem during the callback. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_SetHintWithPriority @@ -4262,12 +4372,12 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); /** * A callback used to send notifications of hint value changes. @@ -4284,7 +4394,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo * hint value. SDL holds a lock on the hint subsystem when * calling this callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ @@ -4300,16 +4410,16 @@ typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * \param callback An SDL_HintCallback function that will be called when the * hint value changes. * \param userdata a pointer to pass to the callback function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveHintCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); /** * Remove a function watching a particular hint. @@ -4321,7 +4431,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_H * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_init.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_init.h index 5a13947..adf0de8 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_init.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_init.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,10 +22,30 @@ /** * # CategoryInit * - * SDL subsystem init and quit functions. + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). */ - #ifndef SDL_init_h_ #define SDL_init_h_ @@ -47,7 +67,7 @@ extern "C" { * These are the flags which may be passed to SDL_Init(). You should specify * the subsystems which you will be using in your application. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -57,9 +77,8 @@ extern "C" { */ typedef Uint32 SDL_InitFlags; -#define SDL_INIT_TIMER 0x00000001u #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ -#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */ #define SDL_INIT_HAPTIC 0x00001000u #define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ @@ -85,7 +104,7 @@ typedef Uint32 SDL_InitFlags; * [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. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AppResult { @@ -94,10 +113,70 @@ typedef enum SDL_AppResult SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ } SDL_AppResult; +/** + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); + +/** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ 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); + +/** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); + +/** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. @@ -117,11 +196,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * * `flags` may be any of the following OR'd together: * - * - `SDL_INIT_TIMER`: timer subsystem * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem + * subsystem, should be initialized on the main thread. * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem @@ -143,10 +221,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * SDL_SetAppMetadataProperty(). * * \param flags subsystem initialization flags. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty @@ -155,7 +233,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * \sa SDL_SetMainReady * \sa SDL_WasInit */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Init(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); /** * Compatibility function to initialize the SDL library. @@ -163,16 +241,16 @@ extern SDL_DECLSPEC SDL_bool 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit * \sa SDL_QuitSubSystem */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); /** * Shut down specific SDL subsystems. @@ -182,7 +260,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem * \sa SDL_Quit @@ -196,7 +274,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_InitSubSystem @@ -214,13 +292,70 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); * application is shutdown, but it is not wise to do this from a library or * other dynamically loaded code. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_QuitSubSystem */ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); +/** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void); + +/** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata); + +/** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete); + /** * Specify basic metadata about your app. * @@ -248,16 +383,16 @@ 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadataProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); /** * Specify metadata about your app through a set of properties. @@ -274,7 +409,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * Multiple calls to this function are allowed, but various state might not * change once it has been set up with a previous call to this function. * - * Once set, this metadata can be read using SDL_GetMetadataProperty(). + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). * * These are the supported properties: * @@ -310,17 +445,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * * \param name the name of the metadata property to set. * \param value the value of the property, or NULL to remove that property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); +extern SDL_DECLSPEC 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" @@ -346,7 +481,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name * freed if you call SDL_SetAppMetadataProperty() to set that * property from another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_intrin.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_intrin.h index efba11d..bac6d7a 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_intrin.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_intrin.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -19,8 +19,31 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * Header file for CPU intrinsics for SDL +/* WIKI CATEGORY: Intrinsics */ + +/** + * # CategoryIntrinsics + * + * SDL does some preprocessor gymnastics to determine if any CPU-specific + * compiler intrinsics are available, as this is not necessarily an easy thing + * to calculate, and sometimes depends on quirks of a system, versions of + * build tools, and other external forces. + * + * Apps including SDL's headers will be able to check consistent preprocessor + * definitions to decide if it's safe to use compiler intrinsics for a + * specific CPU architecture. This check only tells you that the compiler is + * capable of using those intrinsics; at runtime, you should still check if + * they are available on the current system with the + * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo) + * , such as SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash + * for using an unsupported CPU instruction. + * + * SDL only sets preprocessor defines for CPU intrinsics if they are + * supported, so apps should check with `#ifdef` and not `#if`. + * + * SDL will also include the appropriate instruction-set-specific support + * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will also + * `#include ` as well. */ #ifndef SDL_intrin_h_ @@ -28,6 +51,169 @@ #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LSX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LASX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports ARM NEON intrinsics. + * + * If this macro is defined, SDL will have already included `` + * ``, ``, and ``, as appropriate. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NEON_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports PowerPC Altivec intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALTIVEC_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel MMX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + */ +#define SDL_MMX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE3 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE3_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE4_1_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + */ +#define SDL_SSE4_2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX2_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics. + * + * AVX-512F is also sometimes referred to as "AVX-512 Foundation." + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX2_INTRINSICS + */ +#define SDL_AVX512F_INTRINSICS 1 +#endif + /* Need to do this here because intrin.h has C++ code in it */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) @@ -81,7 +267,21 @@ _m_prefetch(void *__P) #endif #endif /* compiler version */ -#if defined(__clang__) && defined(__has_attribute) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro to decide if the compiler supports `__attribute__((target))`. + * + * Even though this is defined in SDL's public headers, it is generally not + * used directly by apps. Apps should probably just use SDL_TARGETING + * directly, instead. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) # if __has_attribute(target) # define SDL_HAS_TARGET_ATTRIBS # endif @@ -91,7 +291,55 @@ _m_prefetch(void *__P) # define SDL_HAS_TARGET_ATTRIBS #endif -#ifdef SDL_HAS_TARGET_ATTRIBS + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a function as targeting a specific CPU architecture. + * + * This is a hint to the compiler that a function should be built with support + * for a CPU instruction set that might be different than the rest of the + * program. + * + * The particulars of this are explained in the GCC documentation: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute + * + * An example of using this feature is to turn on SSE2 support for a specific + * function, even if the rest of the source code is not compiled to use SSE2 + * code: + * + * ```c + * #ifdef SDL_SSE2_INTRINSICS + * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) { + * ...use SSE2 intrinsic functions, etc... + * } + * #endif + * + * // later... + * #ifdef SDL_SSE2_INTRINSICS + * if (SDL_HasSSE2()) { + * DoSomethingWithSSE2(str); + * } + * #endif + * ``` + * + * The application is, on a whole, built without SSE2 instructions, so it will + * run on Intel machines that don't support SSE2. But then at runtime, it + * checks if the system supports the instructions, and then calls into a + * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't + * used on platforms that don't have SSE2 at all. + * + * On compilers without target support, this is defined to nothing. + * + * This symbol is used by SDL internally, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TARGETING(x) __attribute__((target(x))) + +#elif defined(SDL_HAS_TARGET_ATTRIBS) # define SDL_TARGETING(x) __attribute__((target(x))) #else # define SDL_TARGETING(x) diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_iostream.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_iostream.h index a306deb..4ca1609 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_iostream.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_iostream.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,7 @@ * # CategoryIOStream * * SDL provides an abstract interface for reading and writing data streams. It - * offers implementations for files, memory, etc, and the app can provideo + * offers implementations for files, memory, etc, and the app can provide * their own implementations, too. * * SDL_IOStream is not related to the standard C++ iostream class, other than @@ -48,7 +48,7 @@ extern "C" { /** * SDL_IOStream status, set by a read or write operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOStatus { @@ -66,13 +66,13 @@ typedef enum SDL_IOStatus * These map to the same "whence" concept that `fseek` or `lseek` use in the * standard C runtime. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOWhence { SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ - SDL_IO_SEEK_END, /**< Seek relative to the end of data */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ } SDL_IOWhence; /** @@ -83,10 +83,17 @@ typedef enum SDL_IOWhence * already offers several common types of I/O streams, via functions like * SDL_IOFromFile() and SDL_IOFromMem(). * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_IOStreamInterface { + /* The version of this interface */ + Uint32 version; + /** * Return the number of bytes in this SDL_IOStream * @@ -126,18 +133,41 @@ typedef struct SDL_IOStreamInterface */ size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + /** * Close and free any allocated resources. * - * The SDL_IOStream is still destroyed even if this fails, so clean up anything - * even if flushing to disk returns an error. + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. * - * \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data. + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); } SDL_IOStreamInterface; +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); /** * The read/write operation structure. @@ -147,7 +177,7 @@ typedef struct SDL_IOStreamInterface * SDL_OpenIO() to provide their own stream implementation behind this * struct's abstract interface. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_IOStream SDL_IOStream; @@ -217,6 +247,8 @@ typedef struct SDL_IOStream SDL_IOStream; * than your app, trying to use this pointer will almost certainly result in * a crash! This is mostly a problem on Windows; make sure you build SDL and * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access * the filesystem. If SDL used some other method to access the filesystem, @@ -228,9 +260,12 @@ typedef struct SDL_IOStream SDL_IOStream; * \returns a pointer to the SDL_IOStream structure that is created or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -240,6 +275,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" /** @@ -257,15 +293,25 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromConstMem * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -273,6 +319,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons */ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + /** * Use this function to prepare a read-only memory buffer for use with * SDL_IOStream. @@ -290,12 +339,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * If you need to write to a memory buffer, you should use SDL_IOFromMem() * with a writable buffer of memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromMem * \sa SDL_CloseIO @@ -323,7 +381,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO * \sa SDL_ReadIO @@ -347,20 +407,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * read/write a common data source, you should use the built-in * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. * - * You must free the returned pointer with SDL_CloseIO(). - * * This function makes a copy of `iface` and the caller does not need to keep - * this data around after this call. + * it around after this call. * - * \param iface the function pointers that implement this SDL_IOStream. - * \param userdata the app-controlled pointer that is passed to iface's - * functions when called. + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a pointer to the allocated memory on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE * \sa SDL_IOFromConstMem * \sa SDL_IOFromFile * \sa SDL_IOFromMem @@ -372,21 +433,32 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any * resources used by the stream and frees the SDL_IOStream itself. This - * returns SDL_TRUE on success, or SDL_FALSE if the stream failed to flush to - * its output (e.g. to disk). + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). * - * Note that if this fails to flush the stream to disk, this function reports - * an error, but the SDL_IOStream is still invalid once this function returns. + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. * * \param context SDL_IOStream structure to close. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenIO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); /** * Get the properties associated with an SDL_IOStream. @@ -395,7 +467,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); @@ -413,10 +487,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *c * \param context the SDL_IOStream to query. * \returns an SDL_IOStatus enum with the current state. * - * \threadsafety This function should not be called at the same time that - * another thread is operating on the same SDL_IOStream. + * \threadsafety This function is not thread safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); @@ -428,7 +501,9 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); * negative error code on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); @@ -450,10 +525,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * negative. * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, * `SDL_IO_SEEK_END`. - * \returns the final offset in the data stream after the seek or a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TellIO */ @@ -471,7 +548,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs * \returns the current offset in the stream, or -1 if the information can not * be determined. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SeekIO */ @@ -481,10 +560,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * Read from a data source. * * This function reads up `size` bytes from the data source to the area - * pointed at by `ptr`. This function may read less bytes than requested. It - * will return zero when the data stream is completely read, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR. + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. * * \param context a pointer to an SDL_IOStream structure. * \param ptr a pointer to a buffer to read data into. @@ -492,7 +573,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * \returns the number of bytes read, or 0 on end of file or other failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WriteIO * \sa SDL_GetIOStatus @@ -519,11 +602,14 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \returns the number of bytes written, which will be less than `size` on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_ReadIO * \sa SDL_SeekIO + * \sa SDL_FlushIO * \sa SDL_GetIOStatus */ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); @@ -540,7 +626,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOvprintf * \sa SDL_WriteIO @@ -558,13 +646,35 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_WriteIO */ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + /** * Load all the data from an SDL data stream. * @@ -575,17 +685,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * The data should be freed with SDL_free(). * * \param src the SDL_IOStream to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio); +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); /** * Load all the data from a file path. @@ -601,12 +715,55 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile */ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); +/** + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); + +/** + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); + /** * \name Read endian functions * @@ -617,26 +774,63 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi /** * Use this function to read a byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure or EOF; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); /** * Use this function to read a signed byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of little-endian data from an @@ -645,30 +839,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value) * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data. - * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); - -/** - * Use this function to read 16 bits of little-endian data from an - * SDL_IOStream and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -677,14 +862,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -693,14 +885,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -709,14 +908,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -725,14 +931,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -741,14 +954,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -757,14 +977,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -773,14 +1000,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -789,14 +1023,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -805,14 +1046,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -821,14 +1069,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); /* @} *//* Read endian functions */ /** @@ -843,24 +1098,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); /** * Use this function to write a signed byte to an SDL_IOStream. * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -872,12 +1131,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value) * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -889,12 +1150,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -905,12 +1168,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -921,12 +1186,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -938,12 +1205,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -955,12 +1224,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -971,12 +1242,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -987,12 +1260,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1004,12 +1279,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1021,12 +1298,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1037,12 +1316,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1053,12 +1334,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); /* @} *//* Write endian functions */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_joystick.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_joystick.h index 43bc1e9..d15668b 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_joystick.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_joystick.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,8 +25,8 @@ * SDL joystick support. * * This is the lower-level joystick handling. If you want the simpler option, - * where what buttons does what is well-defined, you should use the gamepad - * API instead. + * where what each button does is well-defined, you should use the gamepad API + * instead. * * The term "instance_id" is the current instantiation of a joystick device in * the system, if the joystick is removed and then re-inserted then it will @@ -81,7 +81,7 @@ extern SDL_Mutex *SDL_joystick_lock; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Joystick SDL_Joystick; @@ -93,7 +93,7 @@ typedef struct SDL_Joystick SDL_Joystick; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_JoystickID; @@ -107,7 +107,7 @@ typedef Uint32 SDL_JoystickID; * This is by no means a complete list of everything that can be plugged into * a computer. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickType { @@ -120,7 +120,8 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_GUITAR, SDL_JOYSTICK_TYPE_DRUM_KIT, SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT } SDL_JoystickType; /** @@ -129,7 +130,7 @@ typedef enum SDL_JoystickType * This is used by SDL_GetJoystickConnectionState to report how a device is * connected to the system. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickConnectionState { @@ -142,7 +143,7 @@ typedef enum SDL_JoystickConnectionState /** * The largest value an SDL_Joystick's axis can report. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MIN */ @@ -153,19 +154,13 @@ typedef enum SDL_JoystickConnectionState * * This is a negative number! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MAX */ #define SDL_JOYSTICK_AXIS_MIN -32768 -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - /* Function prototypes */ /** @@ -175,27 +170,27 @@ typedef enum SDL_JoystickConnectionState * joysticks while processing to guarantee that the joystick list won't change * and joystick and gamepad events will not be delivered. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); /** * Unlocking for atomic access to the joystick API. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); /** * Return whether a joystick is currently connected. * - * \returns SDL_TRUE if a joystick is connected, SDL_FALSE otherwise. + * \returns true if a joystick is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. @@ -206,7 +201,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasJoystick * \sa SDL_OpenJoystick @@ -222,7 +217,7 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickName * \sa SDL_GetJoysticks @@ -238,7 +233,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPath * \sa SDL_GetJoysticks @@ -253,7 +248,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a joystick, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoysticks @@ -269,7 +264,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID i * \returns the GUID of the selected joystick. If called with an invalid * instance_id, this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUID * \sa SDL_GUIDToString @@ -286,7 +281,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID ins * \returns the USB vendor ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendor * \sa SDL_GetJoysticks @@ -303,7 +298,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID ins * \returns the USB product ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProduct * \sa SDL_GetJoysticks @@ -320,7 +315,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID in * \returns the product version of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersion * \sa SDL_GetJoysticks @@ -337,7 +332,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_Joysti * invalid instance_id, this function returns * `SDL_JOYSTICK_TYPE_UNKNOWN`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickType * \sa SDL_GetJoysticks @@ -354,7 +349,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti * \returns a joystick identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseJoystick */ @@ -367,7 +362,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID insta * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); @@ -378,7 +373,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_SetJoystickPlayerIndex @@ -388,7 +383,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int pl /** * The structure that describes a virtual joystick touchpad. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -401,7 +396,7 @@ typedef struct SDL_VirtualJoystickTouchpadDesc /** * The structure that describes a virtual joystick sensor. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -414,16 +409,19 @@ typedef struct SDL_VirtualJoystickSensorDesc /** * The structure that describes a virtual joystick. * - * All elements of this structure are optional and can be left 0. + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE * \sa SDL_VirtualJoystickSensorDesc * \sa SDL_VirtualJoystickTouchpadDesc */ typedef struct SDL_VirtualJoystickDesc { + Uint32 version; /**< the version of this interface */ Uint16 type; /**< `SDL_JoystickType` */ Uint16 padding; /**< unused */ Uint16 vendor_id; /**< the USB vendor ID of this joystick */ @@ -446,22 +444,32 @@ typedef struct SDL_VirtualJoystickDesc void *userdata; /**< User data pointer passed to callbacks */ void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - SDL_bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - SDL_bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - SDL_bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - SDL_bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - SDL_bool (SDLCALL *SetSensorsEnabled)(void *userdata, SDL_bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ } SDL_VirtualJoystickDesc; +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + /** * Attach a new virtual joystick. * - * \param desc joystick description. + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DetachVirtualJoystick */ @@ -472,24 +480,24 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V * * \param instance_id the joystick instance ID, previously returned from * SDL_AttachVirtualJoystick(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); /** * Query whether or not a joystick is virtual. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * \returns true if the joystick is virtual, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); /** * Set the state of an axis on an opened virtual joystick. @@ -507,12 +515,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instan * \param joystick the virtual joystick on which to set state. * \param axis the index of the axis on the virtual joystick to update. * \param value the new value for the specified axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); /** * Generate ball motion on an opened virtual joystick. @@ -527,12 +535,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *jo * \param ball the index of the ball on the virtual joystick to update. * \param xrel the relative motion on the X axis. * \param yrel the relative motion on the Y axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); /** * Set the state of a button on an opened virtual joystick. @@ -545,13 +553,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *jo * * \param joystick the virtual joystick on which to set state. * \param button the index of the button on the virtual joystick to update. - * \param value the new value for the specified button. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); /** * Set the state of a hat on an opened virtual joystick. @@ -565,12 +573,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick * * \param joystick the virtual joystick on which to set state. * \param hat the index of the hat on the virtual joystick to update. * \param value the new value for the specified hat. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); /** * Set touchpad finger state on an opened virtual joystick. @@ -585,19 +593,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joy * \param touchpad the index of the touchpad on the virtual joystick to * update. * \param finger the index of the finger on the touchpad to set. - * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the - * finger is released. + * \param down true if the finger is pressed, false if the finger is released. * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param pressure the pressure of the finger. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); /** * Send a sensor update for an opened virtual joystick. @@ -614,12 +621,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick * the sensor reading. * \param data the data associated with the sensor reading. * \param num_values the number of values pointed to by `data`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); /** * Get the properties associated with a joystick. @@ -641,7 +648,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joyst * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); @@ -658,7 +665,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickNameForID */ @@ -671,7 +678,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPathForID */ @@ -686,7 +693,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joyst * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the player index, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickPlayerIndex */ @@ -698,14 +705,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param player_index player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); /** * Get the implementation-dependent GUID for the joystick. @@ -717,7 +724,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *jo * this function returns a zero GUID; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GUIDToString @@ -732,7 +739,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendorForID */ @@ -746,7 +753,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductForID */ @@ -760,7 +767,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the product version of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersionForID */ @@ -775,7 +782,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j * \returns the firmware version of the selected joystick, or 0 if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); @@ -788,7 +795,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick * * \returns the serial number of the selected joystick, or NULL if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); @@ -798,7 +805,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the SDL_JoystickType of the selected joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickTypeForID */ @@ -817,7 +824,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j * \param crc16 a pointer filled in with a CRC used to distinguish different * products with the same VID/PID, or 0 if not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID */ @@ -827,12 +834,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 * * Get the status of a specified joystick. * * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); /** * Get the instance ID of an opened joystick. @@ -841,7 +848,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic * \returns the instance ID of the specified joystick on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); @@ -856,7 +863,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst * \returns the number of axis controls/number of axes on success or -1 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickAxis * \sa SDL_GetNumJoystickBalls @@ -877,7 +884,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); * \returns the number of trackballs on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickBall * \sa SDL_GetNumJoystickAxes @@ -893,7 +900,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); * \returns the number of POV hats on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickHat * \sa SDL_GetNumJoystickAxes @@ -909,7 +916,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); * \returns the number of buttons on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickButton * \sa SDL_GetNumJoystickAxes @@ -927,12 +934,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick * * \param enabled whether to process joystick events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_JoystickEventsEnabled * \sa SDL_UpdateJoysticks */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); /** * Query the state of joystick event processing. @@ -941,14 +948,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); * yourself and check the state of the joystick when you want joystick * information. * - * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE - * otherwise. + * \returns true if joystick events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); /** * Update the current state of the open joysticks. @@ -956,7 +962,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); * This is called automatically by the event loop if any joystick events are * enabled. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); @@ -978,7 +984,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); * \returns a 16-bit signed integer representing the current position of the * axis or 0 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickAxes */ @@ -994,11 +1000,11 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i * \param joystick an SDL_Joystick structure containing joystick information. * \param axis the axis to query; the axis indices start at index 0. * \param state upon return, the initial value is supplied here. - * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \returns true if this axis has any initial value, or false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); /** * Get the ball axis change since the last poll. @@ -1012,14 +1018,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic * \param ball the ball index to query; ball indices start at index 0. * \param dx stores the difference in the x axis position since the last poll. * \param dy stores the difference in the y axis position since the last poll. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickBalls */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); /** * Get the current state of a POV hat on a joystick. @@ -1030,7 +1036,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickHats */ @@ -1052,13 +1058,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickButtons */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); /** * Start a rumble effect. @@ -1075,11 +1081,11 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE, or SDL_FALSE if rumble isn't supported on this joystick. + * \returns true, or false if rumble isn't supported on this joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the joystick's triggers. @@ -1101,14 +1107,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a joystick's LED color. @@ -1123,12 +1129,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *jo * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** * Send a joystick specific effect packet. @@ -1136,19 +1142,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, * \param joystick the joystick to affect. * \param data the data to send to the joystick. * \param size the size of the data to send to the joystick. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); /** * Close a joystick previously opened with SDL_OpenJoystick(). * * \param joystick the joystick device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenJoystick */ @@ -1162,7 +1168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); @@ -1183,7 +1189,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keyboard.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keyboard.h index ec6c3f2..afa77b6 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keyboard.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keyboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeyboard * * SDL keyboard management. + * + * Please refer to the Best Keyboard Practices document for details on how + * best to accept keyboard input in various types of programs: + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keyboard_h_ @@ -31,6 +36,9 @@ #include #include #include +#include +#include +#include #include #include @@ -47,7 +55,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_KeyboardID; @@ -56,13 +64,15 @@ typedef Uint32 SDL_KeyboardID; /** * Return whether a keyboard is currently connected. * - * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise. + * \returns true if a keyboard is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); /** * Get a list of currently connected keyboards. @@ -78,7 +88,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardNameForID * \sa SDL_HasKeyboard @@ -94,7 +106,9 @@ extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); * \returns the name of the selected keyboard or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ @@ -105,7 +119,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID * * \returns the window with keyboard focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); @@ -116,9 +132,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * valid for the whole lifetime of the application and should not be freed by * the caller. * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. + * A array element with a value of true means that the key is pressed and a + * value of false means that it is not. Indexes into this array are obtained + * by using SDL_Scancode values. * * Use SDL_PumpEvents() to update the state array. * @@ -133,19 +149,23 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PumpEvents * \sa SDL_ResetKeyboard */ -extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys); +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); /** * Clear the state of the keyboard. * * This function will generate key up events for all pressed keys. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState */ @@ -157,7 +177,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); * \returns an OR'd combination of the modifier keys for the keyboard. See * SDL_Keymod for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState * \sa SDL_SetModState @@ -177,7 +199,9 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * * \param modstate the desired SDL_Keymod for the keyboard. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetModState */ @@ -189,21 +213,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * If you want to get the keycode as it would be delivered in key events, * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should - * pass `key_event` as SDL_TRUE. Otherwise this function simply translates the + * pass `key_event` as true. Otherwise this function simply translates the * scancode based on the given modifier state. * * \param scancode the desired SDL_Scancode to query. * \param modstate the modifier state to use when translating the scancode to * a keycode. - * \param key_event SDL_TRUE if the keycode will be used in key events. + * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyName * \sa SDL_GetScancodeFromKey */ -extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, SDL_bool key_event); +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); /** * Get the scancode corresponding to the given key code according to the @@ -217,7 +243,9 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan * scancode generates this key, may be NULL. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetScancodeName @@ -231,14 +259,16 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \param name the name to use for the scancode, encoded as UTF-8. The string * is not copied, so the pointer given to this function must stay * valid while SDL is being used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeName */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); /** * Get a human-readable name for a scancode. @@ -256,7 +286,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, * \returns a pointer to the name for the scancode. If the scancode doesn't * have a name this function returns an empty string (""). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeFromKey * \sa SDL_GetScancodeFromName @@ -271,7 +303,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scanco * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't * recognized; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetScancodeFromKey @@ -284,10 +318,14 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * * If the key doesn't have a name, this function returns an empty string (""). * + * Letters will be presented in their uppercase form, if applicable. + * * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetKeyFromScancode @@ -302,7 +340,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetKeyName @@ -319,20 +359,24 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * \param window the window to enable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInputWithProperties * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); /** * Text input type. @@ -341,7 +385,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); * value is valid on every platform, but where a value isn't supported, a * reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -361,12 +405,11 @@ typedef enum SDL_TextInputType /** * Auto capitalization type. * - * These are the valid values for - * SDL_PROP_TEXTINPUT_AUTOCAPITALIZATION_NUMBER. Not every value is valid on - * every platform, but where a value isn't supported, a reasonable fallback - * will be used. + * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. + * Not every value is valid on every platform, but where a value isn't + * supported, a reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -388,7 +431,9 @@ typedef enum SDL_Capitalization * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * These are the supported properties: * @@ -400,11 +445,11 @@ typedef enum SDL_Capitalization * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail * addresses, usernames, and passwords. * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion - * and auto correction, defaults to SDL_TRUE. + * and auto correction, defaults to true. * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text - * are allowed. This defaults to SDL_TRUE if SDL_HINT_RETURN_KEY_HIDES_IME - * is "0" or is not set, and defaults to SDL_FALSE if - * SDL_HINT_RETURN_KEY_HIDES_IME is "1". + * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is + * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME + * is "1". * * On Android you can directly specify the input type: * @@ -414,17 +459,19 @@ typedef enum SDL_Capitalization * * \param window the window to enable text input. * \param props the properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInput * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" @@ -436,13 +483,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window * Check whether or not Unicode text input events are enabled for a window. * * \param window the window to check. - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * \returns true if text input events are enabled else false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); /** * Stop receiving any text input events in a window. @@ -451,28 +500,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); * it. * * \param window the window to disable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); /** * Dismiss the composition window/IME without disabling the subsystem. * * \param window the window to affect. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); /** * Set the area used to type Unicode text input. @@ -485,15 +538,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); * coordinates, or NULL to clear it. * \param cursor the offset of the current cursor location relative to * `rect->x`, in window coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextInputArea * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); /** * Get the area used to type Unicode text input. @@ -505,39 +560,45 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, co * may be NULL. * \param cursor a pointer to the offset of the current cursor location * relative to `rect->x`, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); /** * Check whether the platform has screen keyboard support. * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. + * \returns true if the platform has some screen keyboard support or false if + * not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_ScreenKeyboardShown */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * Check whether the screen keyboard is shown for given window. * * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * \returns true if screen keyboard is shown or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasScreenKeyboardSupport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keycode.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keycode.h index 2d03a3d..61b68e7 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keycode.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_keycode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeycode * * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keycode_h_ @@ -42,272 +47,284 @@ * A special exception is the number keys at the top of the keyboard which map * to SDLK_0...SDLK_9 on AZERTY layouts. * - * \since This datatype is available since SDL 3.0.0. + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_Keycode; -#define SDLK_SCANCODE_MASK (1u<<30) +#define SDLK_EXTENDED_MASK (1u << 29) +#define SDLK_SCANCODE_MASK (1u << 30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -#define SDLK_UNKNOWN 0x00000000u /* 0 */ -#define SDLK_RETURN 0x0000000du /* '\r' */ -#define SDLK_ESCAPE 0x0000001bu /* '\x1B' */ -#define SDLK_BACKSPACE 0x00000008u /* '\b' */ -#define SDLK_TAB 0x00000009u /* '\t' */ -#define SDLK_SPACE 0x00000020u /* ' ' */ -#define SDLK_EXCLAIM 0x00000021u /* '!' */ -#define SDLK_DBLAPOSTROPHE 0x00000022u /* '"' */ -#define SDLK_HASH 0x00000023u /* '#' */ -#define SDLK_DOLLAR 0x00000024u /* '$' */ -#define SDLK_PERCENT 0x00000025u /* '%' */ -#define SDLK_AMPERSAND 0x00000026u /* '&' */ -#define SDLK_APOSTROPHE 0x00000027u /* '\'' */ -#define SDLK_LEFTPAREN 0x00000028u /* '(' */ -#define SDLK_RIGHTPAREN 0x00000029u /* ')' */ -#define SDLK_ASTERISK 0x0000002au /* '*' */ -#define SDLK_PLUS 0x0000002bu /* '+' */ -#define SDLK_COMMA 0x0000002cu /* ',' */ -#define SDLK_MINUS 0x0000002du /* '-' */ -#define SDLK_PERIOD 0x0000002eu /* '.' */ -#define SDLK_SLASH 0x0000002fu /* '/' */ -#define SDLK_0 0x00000030u /* '0' */ -#define SDLK_1 0x00000031u /* '1' */ -#define SDLK_2 0x00000032u /* '2' */ -#define SDLK_3 0x00000033u /* '3' */ -#define SDLK_4 0x00000034u /* '4' */ -#define SDLK_5 0x00000035u /* '5' */ -#define SDLK_6 0x00000036u /* '6' */ -#define SDLK_7 0x00000037u /* '7' */ -#define SDLK_8 0x00000038u /* '8' */ -#define SDLK_9 0x00000039u /* '9' */ -#define SDLK_COLON 0x0000003au /* ':' */ -#define SDLK_SEMICOLON 0x0000003bu /* ';' */ -#define SDLK_LESS 0x0000003cu /* '<' */ -#define SDLK_EQUALS 0x0000003du /* '=' */ -#define SDLK_GREATER 0x0000003eu /* '>' */ -#define SDLK_QUESTION 0x0000003fu /* '?' */ -#define SDLK_AT 0x00000040u /* '@' */ -#define SDLK_LEFTBRACKET 0x0000005bu /* '[' */ -#define SDLK_BACKSLASH 0x0000005cu /* '\\' */ -#define SDLK_RIGHTBRACKET 0x0000005du /* ']' */ -#define SDLK_CARET 0x0000005eu /* '^' */ -#define SDLK_UNDERSCORE 0x0000005fu /* '_' */ -#define SDLK_GRAVE 0x00000060u /* '`' */ -#define SDLK_A 0x00000061u /* 'a' */ -#define SDLK_B 0x00000062u /* 'b' */ -#define SDLK_C 0x00000063u /* 'c' */ -#define SDLK_D 0x00000064u /* 'd' */ -#define SDLK_E 0x00000065u /* 'e' */ -#define SDLK_F 0x00000066u /* 'f' */ -#define SDLK_G 0x00000067u /* 'g' */ -#define SDLK_H 0x00000068u /* 'h' */ -#define SDLK_I 0x00000069u /* 'i' */ -#define SDLK_J 0x0000006au /* 'j' */ -#define SDLK_K 0x0000006bu /* 'k' */ -#define SDLK_L 0x0000006cu /* 'l' */ -#define SDLK_M 0x0000006du /* 'm' */ -#define SDLK_N 0x0000006eu /* 'n' */ -#define SDLK_O 0x0000006fu /* 'o' */ -#define SDLK_P 0x00000070u /* 'p' */ -#define SDLK_Q 0x00000071u /* 'q' */ -#define SDLK_R 0x00000072u /* 'r' */ -#define SDLK_S 0x00000073u /* 's' */ -#define SDLK_T 0x00000074u /* 't' */ -#define SDLK_U 0x00000075u /* 'u' */ -#define SDLK_V 0x00000076u /* 'v' */ -#define SDLK_W 0x00000077u /* 'w' */ -#define SDLK_X 0x00000078u /* 'x' */ -#define SDLK_Y 0x00000079u /* 'y' */ -#define SDLK_Z 0x0000007au /* 'z' */ -#define SDLK_LEFTBRACE 0x0000007bu /* '{' */ -#define SDLK_PIPE 0x0000007cu /* '|' */ -#define SDLK_RIGHTBRACE 0x0000007du /* '}' */ -#define SDLK_TILDE 0x0000007eu /* '~' */ -#define SDLK_DELETE 0x0000007fu /* '\x7F' */ -#define SDLK_PLUSMINUS 0x000000b1u /* '±' */ -#define SDLK_CAPSLOCK 0x40000039u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ -#define SDLK_F1 0x4000003au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ -#define SDLK_F2 0x4000003bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ -#define SDLK_F3 0x4000003cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ -#define SDLK_F4 0x4000003du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ -#define SDLK_F5 0x4000003eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ -#define SDLK_F6 0x4000003fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ -#define SDLK_F7 0x40000040u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ -#define SDLK_F8 0x40000041u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ -#define SDLK_F9 0x40000042u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ -#define SDLK_F10 0x40000043u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ -#define SDLK_F11 0x40000044u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ -#define SDLK_F12 0x40000045u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ -#define SDLK_PRINTSCREEN 0x40000046u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ -#define SDLK_SCROLLLOCK 0x40000047u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ -#define SDLK_PAUSE 0x40000048u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ -#define SDLK_INSERT 0x40000049u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ -#define SDLK_HOME 0x4000004au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ -#define SDLK_PAGEUP 0x4000004bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ -#define SDLK_END 0x4000004du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ -#define SDLK_PAGEDOWN 0x4000004eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ -#define SDLK_RIGHT 0x4000004fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ -#define SDLK_LEFT 0x40000050u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ -#define SDLK_DOWN 0x40000051u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ -#define SDLK_UP 0x40000052u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ -#define SDLK_NUMLOCKCLEAR 0x40000053u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ -#define SDLK_KP_DIVIDE 0x40000054u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ -#define SDLK_KP_MULTIPLY 0x40000055u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ -#define SDLK_KP_MINUS 0x40000056u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ -#define SDLK_KP_PLUS 0x40000057u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ -#define SDLK_KP_ENTER 0x40000058u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ -#define SDLK_KP_1 0x40000059u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ -#define SDLK_KP_2 0x4000005au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ -#define SDLK_KP_3 0x4000005bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ -#define SDLK_KP_4 0x4000005cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ -#define SDLK_KP_5 0x4000005du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ -#define SDLK_KP_6 0x4000005eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ -#define SDLK_KP_7 0x4000005fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ -#define SDLK_KP_8 0x40000060u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ -#define SDLK_KP_9 0x40000061u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ -#define SDLK_KP_0 0x40000062u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ -#define SDLK_KP_PERIOD 0x40000063u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ -#define SDLK_APPLICATION 0x40000065u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ -#define SDLK_POWER 0x40000066u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ -#define SDLK_KP_EQUALS 0x40000067u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ -#define SDLK_F13 0x40000068u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ -#define SDLK_F14 0x40000069u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ -#define SDLK_F15 0x4000006au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ -#define SDLK_F16 0x4000006bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ -#define SDLK_F17 0x4000006cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ -#define SDLK_F18 0x4000006du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ -#define SDLK_F19 0x4000006eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ -#define SDLK_F20 0x4000006fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ -#define SDLK_F21 0x40000070u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ -#define SDLK_F22 0x40000071u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ -#define SDLK_F23 0x40000072u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ -#define SDLK_F24 0x40000073u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ -#define SDLK_EXECUTE 0x40000074u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ -#define SDLK_HELP 0x40000075u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ -#define SDLK_MENU 0x40000076u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ -#define SDLK_SELECT 0x40000077u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ -#define SDLK_STOP 0x40000078u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ -#define SDLK_AGAIN 0x40000079u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ -#define SDLK_UNDO 0x4000007au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ -#define SDLK_CUT 0x4000007bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ -#define SDLK_COPY 0x4000007cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ -#define SDLK_PASTE 0x4000007du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ -#define SDLK_FIND 0x4000007eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ -#define SDLK_MUTE 0x4000007fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ -#define SDLK_VOLUMEUP 0x40000080u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ -#define SDLK_VOLUMEDOWN 0x40000081u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ -#define SDLK_KP_COMMA 0x40000085u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ -#define SDLK_KP_EQUALSAS400 0x40000086u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ -#define SDLK_ALTERASE 0x40000099u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ -#define SDLK_SYSREQ 0x4000009au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ -#define SDLK_CANCEL 0x4000009bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ -#define SDLK_CLEAR 0x4000009cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ -#define SDLK_PRIOR 0x4000009du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ -#define SDLK_RETURN2 0x4000009eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ -#define SDLK_SEPARATOR 0x4000009fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ -#define SDLK_OUT 0x400000a0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ -#define SDLK_OPER 0x400000a1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ -#define SDLK_CLEARAGAIN 0x400000a2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ -#define SDLK_CRSEL 0x400000a3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ -#define SDLK_EXSEL 0x400000a4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ -#define SDLK_KP_00 0x400000b0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ -#define SDLK_KP_000 0x400000b1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ -#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ -#define SDLK_DECIMALSEPARATOR 0x400000b3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ -#define SDLK_CURRENCYUNIT 0x400000b4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ -#define SDLK_CURRENCYSUBUNIT 0x400000b5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ -#define SDLK_KP_LEFTPAREN 0x400000b6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ -#define SDLK_KP_RIGHTPAREN 0x400000b7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ -#define SDLK_KP_LEFTBRACE 0x400000b8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ -#define SDLK_KP_RIGHTBRACE 0x400000b9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ -#define SDLK_KP_TAB 0x400000bau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ -#define SDLK_KP_BACKSPACE 0x400000bbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ -#define SDLK_KP_A 0x400000bcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ -#define SDLK_KP_B 0x400000bdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ -#define SDLK_KP_C 0x400000beu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ -#define SDLK_KP_D 0x400000bfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ -#define SDLK_KP_E 0x400000c0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ -#define SDLK_KP_F 0x400000c1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ -#define SDLK_KP_XOR 0x400000c2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ -#define SDLK_KP_POWER 0x400000c3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ -#define SDLK_KP_PERCENT 0x400000c4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ -#define SDLK_KP_LESS 0x400000c5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ -#define SDLK_KP_GREATER 0x400000c6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ -#define SDLK_KP_AMPERSAND 0x400000c7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ -#define SDLK_KP_DBLAMPERSAND 0x400000c8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ -#define SDLK_KP_VERTICALBAR 0x400000c9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ -#define SDLK_KP_DBLVERTICALBAR 0x400000cau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ -#define SDLK_KP_COLON 0x400000cbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ -#define SDLK_KP_HASH 0x400000ccu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ -#define SDLK_KP_SPACE 0x400000cdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ -#define SDLK_KP_AT 0x400000ceu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ -#define SDLK_KP_EXCLAM 0x400000cfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ -#define SDLK_KP_MEMSTORE 0x400000d0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ -#define SDLK_KP_MEMRECALL 0x400000d1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ -#define SDLK_KP_MEMCLEAR 0x400000d2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ -#define SDLK_KP_MEMADD 0x400000d3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ -#define SDLK_KP_MEMSUBTRACT 0x400000d4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ -#define SDLK_KP_MEMMULTIPLY 0x400000d5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ -#define SDLK_KP_MEMDIVIDE 0x400000d6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ -#define SDLK_KP_PLUSMINUS 0x400000d7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ -#define SDLK_KP_CLEAR 0x400000d8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ -#define SDLK_KP_CLEARENTRY 0x400000d9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ -#define SDLK_KP_BINARY 0x400000dau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ -#define SDLK_KP_OCTAL 0x400000dbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ -#define SDLK_KP_DECIMAL 0x400000dcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ -#define SDLK_KP_HEXADECIMAL 0x400000ddu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ -#define SDLK_LCTRL 0x400000e0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ -#define SDLK_LSHIFT 0x400000e1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ -#define SDLK_LALT 0x400000e2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ -#define SDLK_LGUI 0x400000e3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ -#define SDLK_RCTRL 0x400000e4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ -#define SDLK_RSHIFT 0x400000e5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ -#define SDLK_RALT 0x400000e6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ -#define SDLK_RGUI 0x400000e7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ -#define SDLK_MODE 0x40000101u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ -#define SDLK_SLEEP 0x40000102u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ -#define SDLK_WAKE 0x40000103u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ -#define SDLK_CHANNEL_INCREMENT 0x40000104u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ -#define SDLK_CHANNEL_DECREMENT 0x40000105u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ -#define SDLK_MEDIA_PLAY 0x40000106u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ -#define SDLK_MEDIA_PAUSE 0x40000107u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ -#define SDLK_MEDIA_RECORD 0x40000108u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ -#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ -#define SDLK_MEDIA_REWIND 0x4000010au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ -#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ -#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ -#define SDLK_MEDIA_STOP 0x4000010du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ -#define SDLK_MEDIA_EJECT 0x4000010eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ -#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ -#define SDLK_MEDIA_SELECT 0x40000110u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ -#define SDLK_AC_NEW 0x40000111u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ -#define SDLK_AC_OPEN 0x40000112u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ -#define SDLK_AC_CLOSE 0x40000113u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ -#define SDLK_AC_EXIT 0x40000114u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ -#define SDLK_AC_SAVE 0x40000115u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ -#define SDLK_AC_PRINT 0x40000116u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ -#define SDLK_AC_PROPERTIES 0x40000117u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ -#define SDLK_AC_SEARCH 0x40000118u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ -#define SDLK_AC_HOME 0x40000119u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ -#define SDLK_AC_BACK 0x4000011au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ -#define SDLK_AC_FORWARD 0x4000011bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ -#define SDLK_AC_STOP 0x4000011cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ -#define SDLK_AC_REFRESH 0x4000011du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ -#define SDLK_AC_BOOKMARKS 0x4000011eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ -#define SDLK_SOFTLEFT 0x4000011fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ -#define SDLK_SOFTRIGHT 0x40000120u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ -#define SDLK_CALL 0x40000121u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ -#define SDLK_ENDCALL 0x40000122u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_UNKNOWN 0x00000000u /**< 0 */ +#define SDLK_RETURN 0x0000000du /**< '\r' */ +#define SDLK_ESCAPE 0x0000001bu /**< '\x1B' */ +#define SDLK_BACKSPACE 0x00000008u /**< '\b' */ +#define SDLK_TAB 0x00000009u /**< '\t' */ +#define SDLK_SPACE 0x00000020u /**< ' ' */ +#define SDLK_EXCLAIM 0x00000021u /**< '!' */ +#define SDLK_DBLAPOSTROPHE 0x00000022u /**< '"' */ +#define SDLK_HASH 0x00000023u /**< '#' */ +#define SDLK_DOLLAR 0x00000024u /**< '$' */ +#define SDLK_PERCENT 0x00000025u /**< '%' */ +#define SDLK_AMPERSAND 0x00000026u /**< '&' */ +#define SDLK_APOSTROPHE 0x00000027u /**< '\'' */ +#define SDLK_LEFTPAREN 0x00000028u /**< '(' */ +#define SDLK_RIGHTPAREN 0x00000029u /**< ')' */ +#define SDLK_ASTERISK 0x0000002au /**< '*' */ +#define SDLK_PLUS 0x0000002bu /**< '+' */ +#define SDLK_COMMA 0x0000002cu /**< ',' */ +#define SDLK_MINUS 0x0000002du /**< '-' */ +#define SDLK_PERIOD 0x0000002eu /**< '.' */ +#define SDLK_SLASH 0x0000002fu /**< '/' */ +#define SDLK_0 0x00000030u /**< '0' */ +#define SDLK_1 0x00000031u /**< '1' */ +#define SDLK_2 0x00000032u /**< '2' */ +#define SDLK_3 0x00000033u /**< '3' */ +#define SDLK_4 0x00000034u /**< '4' */ +#define SDLK_5 0x00000035u /**< '5' */ +#define SDLK_6 0x00000036u /**< '6' */ +#define SDLK_7 0x00000037u /**< '7' */ +#define SDLK_8 0x00000038u /**< '8' */ +#define SDLK_9 0x00000039u /**< '9' */ +#define SDLK_COLON 0x0000003au /**< ':' */ +#define SDLK_SEMICOLON 0x0000003bu /**< ';' */ +#define SDLK_LESS 0x0000003cu /**< '<' */ +#define SDLK_EQUALS 0x0000003du /**< '=' */ +#define SDLK_GREATER 0x0000003eu /**< '>' */ +#define SDLK_QUESTION 0x0000003fu /**< '?' */ +#define SDLK_AT 0x00000040u /**< '@' */ +#define SDLK_LEFTBRACKET 0x0000005bu /**< '[' */ +#define SDLK_BACKSLASH 0x0000005cu /**< '\\' */ +#define SDLK_RIGHTBRACKET 0x0000005du /**< ']' */ +#define SDLK_CARET 0x0000005eu /**< '^' */ +#define SDLK_UNDERSCORE 0x0000005fu /**< '_' */ +#define SDLK_GRAVE 0x00000060u /**< '`' */ +#define SDLK_A 0x00000061u /**< 'a' */ +#define SDLK_B 0x00000062u /**< 'b' */ +#define SDLK_C 0x00000063u /**< 'c' */ +#define SDLK_D 0x00000064u /**< 'd' */ +#define SDLK_E 0x00000065u /**< 'e' */ +#define SDLK_F 0x00000066u /**< 'f' */ +#define SDLK_G 0x00000067u /**< 'g' */ +#define SDLK_H 0x00000068u /**< 'h' */ +#define SDLK_I 0x00000069u /**< 'i' */ +#define SDLK_J 0x0000006au /**< 'j' */ +#define SDLK_K 0x0000006bu /**< 'k' */ +#define SDLK_L 0x0000006cu /**< 'l' */ +#define SDLK_M 0x0000006du /**< 'm' */ +#define SDLK_N 0x0000006eu /**< 'n' */ +#define SDLK_O 0x0000006fu /**< 'o' */ +#define SDLK_P 0x00000070u /**< 'p' */ +#define SDLK_Q 0x00000071u /**< 'q' */ +#define SDLK_R 0x00000072u /**< 'r' */ +#define SDLK_S 0x00000073u /**< 's' */ +#define SDLK_T 0x00000074u /**< 't' */ +#define SDLK_U 0x00000075u /**< 'u' */ +#define SDLK_V 0x00000076u /**< 'v' */ +#define SDLK_W 0x00000077u /**< 'w' */ +#define SDLK_X 0x00000078u /**< 'x' */ +#define SDLK_Y 0x00000079u /**< 'y' */ +#define SDLK_Z 0x0000007au /**< 'z' */ +#define SDLK_LEFTBRACE 0x0000007bu /**< '{' */ +#define SDLK_PIPE 0x0000007cu /**< '|' */ +#define SDLK_RIGHTBRACE 0x0000007du /**< '}' */ +#define SDLK_TILDE 0x0000007eu /**< '~' */ +#define SDLK_DELETE 0x0000007fu /**< '\x7F' */ +#define SDLK_PLUSMINUS 0x000000b1u /**< '\xB1' */ +#define SDLK_CAPSLOCK 0x40000039u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ +#define SDLK_F1 0x4000003au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ +#define SDLK_F2 0x4000003bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ +#define SDLK_F3 0x4000003cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ +#define SDLK_F4 0x4000003du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ +#define SDLK_F5 0x4000003eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ +#define SDLK_F6 0x4000003fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ +#define SDLK_F7 0x40000040u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ +#define SDLK_F8 0x40000041u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ +#define SDLK_F9 0x40000042u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ +#define SDLK_F10 0x40000043u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ +#define SDLK_F11 0x40000044u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ +#define SDLK_F12 0x40000045u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ +#define SDLK_PRINTSCREEN 0x40000046u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ +#define SDLK_SCROLLLOCK 0x40000047u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ +#define SDLK_PAUSE 0x40000048u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ +#define SDLK_INSERT 0x40000049u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ +#define SDLK_HOME 0x4000004au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ +#define SDLK_PAGEUP 0x4000004bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ +#define SDLK_END 0x4000004du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ +#define SDLK_PAGEDOWN 0x4000004eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ +#define SDLK_RIGHT 0x4000004fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ +#define SDLK_LEFT 0x40000050u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ +#define SDLK_DOWN 0x40000051u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ +#define SDLK_UP 0x40000052u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ +#define SDLK_NUMLOCKCLEAR 0x40000053u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ +#define SDLK_KP_DIVIDE 0x40000054u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ +#define SDLK_KP_MULTIPLY 0x40000055u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ +#define SDLK_KP_MINUS 0x40000056u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ +#define SDLK_KP_PLUS 0x40000057u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ +#define SDLK_KP_ENTER 0x40000058u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ +#define SDLK_KP_1 0x40000059u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ +#define SDLK_KP_2 0x4000005au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ +#define SDLK_KP_3 0x4000005bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ +#define SDLK_KP_4 0x4000005cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ +#define SDLK_KP_5 0x4000005du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ +#define SDLK_KP_6 0x4000005eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ +#define SDLK_KP_7 0x4000005fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ +#define SDLK_KP_8 0x40000060u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ +#define SDLK_KP_9 0x40000061u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ +#define SDLK_KP_0 0x40000062u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ +#define SDLK_KP_PERIOD 0x40000063u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ +#define SDLK_APPLICATION 0x40000065u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ +#define SDLK_POWER 0x40000066u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ +#define SDLK_KP_EQUALS 0x40000067u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ +#define SDLK_F13 0x40000068u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ +#define SDLK_F14 0x40000069u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ +#define SDLK_F15 0x4000006au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ +#define SDLK_F16 0x4000006bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ +#define SDLK_F17 0x4000006cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ +#define SDLK_F18 0x4000006du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ +#define SDLK_F19 0x4000006eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ +#define SDLK_F20 0x4000006fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ +#define SDLK_F21 0x40000070u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ +#define SDLK_F22 0x40000071u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ +#define SDLK_F23 0x40000072u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ +#define SDLK_F24 0x40000073u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ +#define SDLK_EXECUTE 0x40000074u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ +#define SDLK_HELP 0x40000075u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ +#define SDLK_MENU 0x40000076u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ +#define SDLK_SELECT 0x40000077u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ +#define SDLK_STOP 0x40000078u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ +#define SDLK_AGAIN 0x40000079u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ +#define SDLK_UNDO 0x4000007au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ +#define SDLK_CUT 0x4000007bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ +#define SDLK_COPY 0x4000007cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ +#define SDLK_PASTE 0x4000007du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ +#define SDLK_FIND 0x4000007eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ +#define SDLK_MUTE 0x4000007fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ +#define SDLK_VOLUMEUP 0x40000080u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ +#define SDLK_VOLUMEDOWN 0x40000081u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ +#define SDLK_KP_COMMA 0x40000085u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ +#define SDLK_KP_EQUALSAS400 0x40000086u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ +#define SDLK_ALTERASE 0x40000099u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ +#define SDLK_SYSREQ 0x4000009au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ +#define SDLK_CANCEL 0x4000009bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ +#define SDLK_CLEAR 0x4000009cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ +#define SDLK_PRIOR 0x4000009du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ +#define SDLK_RETURN2 0x4000009eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ +#define SDLK_SEPARATOR 0x4000009fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ +#define SDLK_OUT 0x400000a0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ +#define SDLK_OPER 0x400000a1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ +#define SDLK_CLEARAGAIN 0x400000a2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ +#define SDLK_CRSEL 0x400000a3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ +#define SDLK_EXSEL 0x400000a4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ +#define SDLK_KP_00 0x400000b0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ +#define SDLK_KP_000 0x400000b1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ +#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ +#define SDLK_DECIMALSEPARATOR 0x400000b3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ +#define SDLK_CURRENCYUNIT 0x400000b4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ +#define SDLK_CURRENCYSUBUNIT 0x400000b5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ +#define SDLK_KP_LEFTPAREN 0x400000b6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ +#define SDLK_KP_RIGHTPAREN 0x400000b7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ +#define SDLK_KP_LEFTBRACE 0x400000b8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ +#define SDLK_KP_RIGHTBRACE 0x400000b9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ +#define SDLK_KP_TAB 0x400000bau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ +#define SDLK_KP_BACKSPACE 0x400000bbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ +#define SDLK_KP_A 0x400000bcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ +#define SDLK_KP_B 0x400000bdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ +#define SDLK_KP_C 0x400000beu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ +#define SDLK_KP_D 0x400000bfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ +#define SDLK_KP_E 0x400000c0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ +#define SDLK_KP_F 0x400000c1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ +#define SDLK_KP_XOR 0x400000c2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ +#define SDLK_KP_POWER 0x400000c3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ +#define SDLK_KP_PERCENT 0x400000c4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ +#define SDLK_KP_LESS 0x400000c5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ +#define SDLK_KP_GREATER 0x400000c6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ +#define SDLK_KP_AMPERSAND 0x400000c7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ +#define SDLK_KP_DBLAMPERSAND 0x400000c8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ +#define SDLK_KP_VERTICALBAR 0x400000c9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ +#define SDLK_KP_DBLVERTICALBAR 0x400000cau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ +#define SDLK_KP_COLON 0x400000cbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ +#define SDLK_KP_HASH 0x400000ccu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ +#define SDLK_KP_SPACE 0x400000cdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ +#define SDLK_KP_AT 0x400000ceu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ +#define SDLK_KP_EXCLAM 0x400000cfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ +#define SDLK_KP_MEMSTORE 0x400000d0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ +#define SDLK_KP_MEMRECALL 0x400000d1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ +#define SDLK_KP_MEMCLEAR 0x400000d2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ +#define SDLK_KP_MEMADD 0x400000d3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ +#define SDLK_KP_MEMSUBTRACT 0x400000d4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ +#define SDLK_KP_MEMMULTIPLY 0x400000d5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ +#define SDLK_KP_MEMDIVIDE 0x400000d6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ +#define SDLK_KP_PLUSMINUS 0x400000d7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ +#define SDLK_KP_CLEAR 0x400000d8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ +#define SDLK_KP_CLEARENTRY 0x400000d9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ +#define SDLK_KP_BINARY 0x400000dau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ +#define SDLK_KP_OCTAL 0x400000dbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ +#define SDLK_KP_DECIMAL 0x400000dcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ +#define SDLK_KP_HEXADECIMAL 0x400000ddu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ +#define SDLK_LCTRL 0x400000e0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ +#define SDLK_LSHIFT 0x400000e1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ +#define SDLK_LALT 0x400000e2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ +#define SDLK_LGUI 0x400000e3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ +#define SDLK_RCTRL 0x400000e4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ +#define SDLK_RSHIFT 0x400000e5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ +#define SDLK_RALT 0x400000e6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ +#define SDLK_RGUI 0x400000e7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ +#define SDLK_MODE 0x40000101u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ +#define SDLK_SLEEP 0x40000102u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ +#define SDLK_WAKE 0x40000103u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ +#define SDLK_CHANNEL_INCREMENT 0x40000104u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ +#define SDLK_CHANNEL_DECREMENT 0x40000105u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ +#define SDLK_MEDIA_PLAY 0x40000106u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ +#define SDLK_MEDIA_PAUSE 0x40000107u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ +#define SDLK_MEDIA_RECORD 0x40000108u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ +#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ +#define SDLK_MEDIA_REWIND 0x4000010au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ +#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ +#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ +#define SDLK_MEDIA_STOP 0x4000010du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ +#define SDLK_MEDIA_EJECT 0x4000010eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ +#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ +#define SDLK_MEDIA_SELECT 0x40000110u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ +#define SDLK_AC_NEW 0x40000111u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ +#define SDLK_AC_OPEN 0x40000112u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ +#define SDLK_AC_CLOSE 0x40000113u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ +#define SDLK_AC_EXIT 0x40000114u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ +#define SDLK_AC_SAVE 0x40000115u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ +#define SDLK_AC_PRINT 0x40000116u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ +#define SDLK_AC_PROPERTIES 0x40000117u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ +#define SDLK_AC_SEARCH 0x40000118u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ +#define SDLK_AC_HOME 0x40000119u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ +#define SDLK_AC_BACK 0x4000011au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ +#define SDLK_AC_FORWARD 0x4000011bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ +#define SDLK_AC_STOP 0x4000011cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ +#define SDLK_AC_REFRESH 0x4000011du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ +#define SDLK_AC_BOOKMARKS 0x4000011eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ +#define SDLK_SOFTLEFT 0x4000011fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ +#define SDLK_SOFTRIGHT 0x40000120u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ +#define SDLK_CALL 0x40000121u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ +#define SDLK_ENDCALL 0x40000122u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_LEFT_TAB 0x20000001u /**< Extended key Left Tab */ +#define SDLK_LEVEL5_SHIFT 0x20000002u /**< Extended key Level 5 Shift */ +#define SDLK_MULTI_KEY_COMPOSE 0x20000003u /**< Extended key Multi-key Compose */ +#define SDLK_LMETA 0x20000004u /**< Extended key Left Meta */ +#define SDLK_RMETA 0x20000005u /**< Extended key Right Meta */ +#define SDLK_LHYPER 0x20000006u /**< Extended key Left Hyper */ +#define SDLK_RHYPER 0x20000007u /**< Extended key Right Hyper */ /** * Valid key modifiers (possibly OR'd together). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint16 SDL_Keymod; #define SDL_KMOD_NONE 0x0000u /**< no modifier is applicable. */ #define SDL_KMOD_LSHIFT 0x0001u /**< the left Shift key is down. */ #define SDL_KMOD_RSHIFT 0x0002u /**< the right Shift key is down. */ +#define SDL_KMOD_LEVEL5 0x0004u /**< the Level 5 Shift key is down. */ #define SDL_KMOD_LCTRL 0x0040u /**< the left Ctrl (Control) key is down. */ #define SDL_KMOD_RCTRL 0x0080u /**< the right Ctrl (Control) key is down. */ #define SDL_KMOD_LALT 0x0100u /**< the left Alt key is down. */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_loadso.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_loadso.h index ab34a38..f8649d7 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_loadso.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_loadso.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ * * System-dependent library loading routines. * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * * Some things to keep in mind: * * - These functions only work on C function names. Other languages may have @@ -38,6 +46,11 @@ * not defined whether or not it goes into the global symbol namespace for * the application. If it does and it conflicts with symbols in your code or * other shared libraries, you will not get the results you expect. :) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that pointer after the library unloads. */ #ifndef SDL_loadso_h_ @@ -52,6 +65,17 @@ extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * @@ -59,12 +83,14 @@ extern "C" { * \returns an opaque pointer to the object handle or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -86,22 +112,29 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); * \returns a pointer to the function or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_locale.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_locale.h index 85d7750..902843e 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_locale.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_locale.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategoryLocale * * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. */ #ifndef SDL_locale_h @@ -47,7 +53,7 @@ extern "C" { * would be "en"), and the country, if not NULL, will be an ISO-3166 country * code (so Canada would be "CA"). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPreferredLocales */ @@ -96,7 +102,7 @@ typedef struct SDL_Locale * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_log.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_log.h index deda238..a56476c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_log.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_log.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,7 @@ /** * # CategoryLog * - * Simple log messages with priorities and categories. A message’s + * Simple log messages with priorities and categories. A message's * SDL_LogPriority signifies how important the message is. A message's * SDL_LogCategory signifies from what domain it belongs to. Every category * has a minimum priority specified: when a message belongs to that category, @@ -76,7 +76,7 @@ extern "C" { * level, the assert category is enabled at the WARN level, test is enabled at * the VERBOSE level and all other categories are enabled at the ERROR level. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogCategory { @@ -87,12 +87,11 @@ typedef enum SDL_LogCategory SDL_LOG_CATEGORY_AUDIO, SDL_LOG_CATEGORY_VIDEO, SDL_LOG_CATEGORY_RENDER, - SDL_LOG_CATEGORY_GPU, SDL_LOG_CATEGORY_INPUT, SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, SDL_LOG_CATEGORY_RESERVED2, SDL_LOG_CATEGORY_RESERVED3, SDL_LOG_CATEGORY_RESERVED4, @@ -117,17 +116,19 @@ typedef enum SDL_LogCategory /** * The predefined log priorities * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogPriority { - SDL_LOG_PRIORITY_VERBOSE = 1, + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, SDL_LOG_PRIORITY_DEBUG, SDL_LOG_PRIORITY_INFO, SDL_LOG_PRIORITY_WARN, SDL_LOG_PRIORITY_ERROR, SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES + SDL_LOG_PRIORITY_COUNT } SDL_LogPriority; @@ -136,7 +137,9 @@ typedef enum SDL_LogPriority * * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriority @@ -149,14 +152,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); * \param category the category to assign a priority to. * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetLogPriority * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriorities */ -extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, - SDL_LogPriority priority); +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); /** * Get the priority of a particular log category. @@ -164,7 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, * \param category the category to query. * \returns the SDL_LogPriority for the requested category. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriority */ @@ -175,7 +181,9 @@ extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); * * This is called by SDL_Quit(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority @@ -192,15 +200,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); * \param priority the SDL_LogPriority to modify. * \param prefix the prefix to use for that log priority, or NULL to use no * prefix. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); /** * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. @@ -209,7 +219,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \param ... additional parameters matching % tokens in the `fmt` string, if * any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LogCritical * \sa SDL_LogDebug @@ -217,11 +229,37 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * @@ -230,7 +268,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -251,7 +291,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -259,6 +301,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -272,7 +315,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -280,6 +325,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogError * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -293,7 +339,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -302,6 +350,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose */ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); @@ -314,7 +363,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -322,6 +373,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -335,7 +387,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogDebug @@ -343,6 +397,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -357,7 +412,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -365,6 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -380,7 +438,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \param fmt a printf() style message format string. * \param ap a variable argument list. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -388,6 +448,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessage + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -398,7 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, /** * The prototype for the log output callback function. * - * This function is called by SDL when there is new text to be logged. + * This function is called by SDL when there is new text to be logged. A mutex + * is held so that this function is never called by more than one thread at + * once. * * \param userdata what was passed as `userdata` to * SDL_SetLogOutputFunction(). @@ -406,10 +469,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, * \param priority the priority of the message. * \param message the message being output. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void); + /** * Get the current log output function. * @@ -418,8 +495,11 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * \param userdata a pointer filled in with the pointer that is passed to * `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_SetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata); @@ -430,8 +510,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction * \param callback an SDL_LogOutputFunction to call instead of the default. * \param userdata a pointer that is passed to `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_GetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main.h index de3c187..2e7a2eb 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,13 +22,29 @@ /** * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() if necessary so that it is called by SDL. * - * For details on how SDL_main works, and how to use it, please refer to: + * In order to make this consistent on all platforms, the application's main() + * should look like this: + * + * ```c + * int main(int argc, char *argv[]) + * { + * } + * ``` + * + * SDL will take care of platform specific details on how it gets called. + * + * This is also where an app can be configured to use the main callbacks, via + * the SDL_MAIN_USE_CALLBACKS macro. + * + * This is a "single-header library," which is to say that including this + * header inserts code into your program, and you should only include it once + * in most cases. SDL.h does not include this header automatically. + * + * For more information, see: * * https://wiki.libsdl.org/SDL3/README/main-functions - * - * (or docs/README-main-functions.md in the SDL source tree) */ #ifndef SDL_main_h_ @@ -39,8 +55,96 @@ #include #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Inform SDL that the app is providing an entry point instead of SDL. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide the + * proper entry point for the platform, and all the other magic details + * needed, like manually calling SDL_SetMainReady. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + */ +#define SDL_MAIN_HANDLED 1 + +/** + * Inform SDL to use the main callbacks instead of main. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide + * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and + * SDL_AppQuit. The app should not provide a `main` function in this case, and + * doing so will likely cause the build to fail. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + * \sa SDL_AppIterate + * \sa SDL_AppQuit + */ +#define SDL_MAIN_USE_CALLBACKS 1 + +/** + * Defined if the target platform offers a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if available, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_AVAILABLE + +/** + * Defined if the target platform _requires_ a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if required, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_NEEDED + +#endif + +#if defined(__has_include) + #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h") + #define SDL_PLATFORM_PRIVATE_MAIN + #endif +#endif + #ifndef SDL_MAIN_HANDLED - #ifdef SDL_PLATFORM_WIN32 + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_private.h" + + #elif defined(SDL_PLATFORM_WIN32) /* On Windows SDL provides WinMain(), which parses the command line and passes the arguments to your main function. @@ -48,20 +152,6 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_WINRT) - /* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - 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 ` - 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 - #elif defined(SDL_PLATFORM_GDK) /* On GDK, SDL provides a main function that initializes the game runtime. @@ -91,8 +181,14 @@ */ #define SDL_MAIN_NEEDED - /* We need to export SDL_main so it can be launched from Java */ - #define SDLMAIN_DECLSPEC SDL_DECLSPEC + /* As this is launched from Java, the real entry point (main() function) + is outside of the the binary built from this code. + This define makes sure that, unlike on other platforms, SDL_main.h + and SDL_main_impl.h export an `SDL_main()` function (to be called + from Java), but don't implement a native `int main(int argc, char* argv[])` + or similar. + */ + #define SDL_MAIN_EXPORTED #elif defined(SDL_PLATFORM_EMSCRIPTEN) /* On Emscripten, SDL provides a main function that converts URL @@ -129,60 +225,36 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_NGAGE) - /* - TODO: not sure if it should be SDL_MAIN_NEEDED, in SDL2 ngage had a - main implementation, but wasn't mentioned in SDL_main.h - */ - #define SDL_MAIN_AVAILABLE - #endif #endif /* SDL_MAIN_HANDLED */ -#ifndef SDLMAIN_DECLSPEC -#define SDLMAIN_DECLSPEC -#endif - -/** - * \file SDL_main.h - * - * The application's main() function must be called with C linkage, - * and should be declared like this: - * - * ```c - * #ifdef __cplusplus - * extern "C" - * #endif - * int main(int argc, char *argv[]) - * { - * } - * ``` - */ #ifdef SDL_WIKI_DOCUMENTATION_SECTION /** - * Inform SDL to use the main callbacks instead of main. + * A macro to tag a main entry point function as exported. * - * SDL does not define this macro, but will check if it is defined when - * including `SDL_main.h`. If defined, SDL will expect the app to provide - * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and - * SDL_AppQuit. The app should not provide a `main` function in this case, and - * doing so will likely cause the build to fail. + * Most platforms don't need this, and the macro will be defined to nothing. + * Some, like Android, keep the entry points in a shared library and need to + * explicitly export the symbols. * - * Please see [README/main-functions](README/main-functions), (or - * docs/README-main-functions.md in the source tree) for a more detailed - * explanation. + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. * - * \since This macro is used by the headers since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit + * \sa SDL_DECLSPEC */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif +#define SDLMAIN_DECLSPEC + +#elif defined(SDL_MAIN_EXPORTED) +/* We need to export SDL_main so it can be launched from external code, + like SDLActivity.java on Android */ +#define SDLMAIN_DECLSPEC SDL_DECLSPEC +#else +/* usually this is empty */ +#define SDLMAIN_DECLSPEC +#endif /* SDL_MAIN_EXPORTED */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main @@ -248,6 +320,8 @@ extern "C" { * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code * that reports success to the platform. * + * This function is called by SDL on the main thread. + * * \param appstate a place where the app can optionally store a pointer for * future use. * \param argc the standard ANSI C main's argc; number of elements in `argv`. @@ -256,9 +330,7 @@ extern "C" { * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppIterate * \sa SDL_AppEvent @@ -301,13 +373,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int a * SDL_AppQuit and terminates with an exit code that reports success to the * platform. * + * This function is called by SDL on the main thread. + * * \param appstate an optional pointer, provided by the app in SDL_AppInit. * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with SDL_AppEvent() + * for events not pushed on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppEvent @@ -320,15 +395,15 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a * standard "main" function, you should not supply this. * - * This function is called as needed by SDL after SDL_AppInit returns 0; It is - * called once for each new event. + * This function is called as needed by SDL after SDL_AppInit returns + * SDL_APP_CONTINUE. It is called once for each new event. * * There is (currently) no guarantee about what thread this will be called * from; whatever thread pushes an event onto SDL's queue will trigger this * function. SDL is responsible for pumping the event queue between each call * to SDL_AppIterate, so in normal operation one should only get events in a * serial fashion, but be careful if you have a thread that explicitly calls - * SDL_PushEvent. + * SDL_PushEvent. SDL itself will push events to the queue on the main thread. * * Events sent to this function are not owned by the app; if you need to save * the data, you should copy it. @@ -352,14 +427,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with + * SDL_AppIterate() or SDL_AppQuit() for events not pushed from + * the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppIterate */ -extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); /** * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -385,15 +462,19 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const * function call is the last time this pointer will be provided, so any * resources to it should be cleaned up here. * + * This function is called by SDL on the main thread. + * * \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. + * \threadsafety SDL_AppEvent() may get called concurrently with this function + * if other threads that push events are still active. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.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 */ @@ -407,7 +488,7 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate); * program completion, and small non-zero values are considered * errors. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); @@ -440,7 +521,7 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); * * \threadsafety This is the program entry point. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); @@ -453,7 +534,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); * will not be changed it is necessary to define SDL_MAIN_HANDLED before * including SDL.h. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init */ @@ -485,7 +566,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); * \threadsafety Generally this is called once, near startup, from the * process's initial thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved); @@ -512,12 +593,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func * \threadsafety It is not safe to call this anywhere except as the only * function call in SDL_main. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) /** * Register a win32 window class for SDL's use. @@ -538,12 +619,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * what is specified here. * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL * will use `GetModuleHandle(NULL)` instead. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); /** * Deregister the win32 window class from an SDL_RegisterApp call. @@ -558,23 +639,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 st * deregistered when the registration counter in SDL_RegisterApp decrements to * zero through calls to this function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ - -#ifdef SDL_PLATFORM_GDK +#endif /* defined(SDL_PLATFORM_WINDOWS) */ /** * Callback from the application to let the suspend continue. * - * \since This function is available since SDL 3.0.0. + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); -#endif /* SDL_PLATFORM_GDK */ - #ifdef __cplusplus } #endif @@ -583,29 +663,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) /* include header-only SDL_main implementations */ - #if defined(SDL_MAIN_USE_CALLBACKS) \ - || defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ - || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) \ - || defined(SDL_PLATFORM_EMSCRIPTEN) - + #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) /* platforms which main (-equivalent) can be implemented in plain C */ #include - - #elif defined(SDL_PLATFORM_WINRT) /* C++ platforms */ - #ifdef __cplusplus - #include - #else - /* Note: to get rid of the following warning, you can #define SDL_MAIN_NOIMPL before including SDL_main.h - * in your C sourcefile that contains the standard main. Do *not* use SDL_MAIN_HANDLED for that, then SDL_main won't find your main()! - */ - #ifdef _MSC_VER - #pragma message("Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C (then continue including SDL_main.h there!) and create a fresh .cpp file that only contains #include ") - #elif defined(__GNUC__) /* gcc, clang, mingw and compatible are matched by this and have #warning */ - #warning "Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C and create a fresh .cpp file that only contains #include " - #endif /* __GNUC__ */ - #endif /* __cplusplus */ - - #endif /* C++ platforms like SDL_PLATFORM_WINRT etc */ + #endif #endif #endif /* SDL_main_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main_impl.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main_impl.h index ad122df..14ebb42 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main_impl.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_main_impl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,7 +29,7 @@ #endif /* if someone wants to include SDL_main.h but doesn't want the main handing magic, - (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first + (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first. SDL_MAIN_NOIMPL is for SDL-internal usage (only affects implementation, not definition of SDL_MAIN_AVAILABLE etc in SDL_main.h) and if the user wants to have the SDL_main implementation (from this header) in another source file @@ -64,10 +64,15 @@ #endif /* SDL_MAIN_USE_CALLBACKS */ - /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */ - #if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) + /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point, + unless the real entry point needs to be somewhere else entirely, like Android where it's in Java code */ + #if (!defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)) && !defined(SDL_MAIN_EXPORTED) - #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_impl_private.h" + + #elif defined(SDL_PLATFORM_WINDOWS) /* these defines/typedefs are needed for the WinMain() definition */ #ifndef WINAPI @@ -82,7 +87,7 @@ #if defined(_MSC_VER) && !defined(SDL_PLATFORM_GDK) /* This is where execution begins [console apps] */ - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int wmain(int argc, wchar_t *wargv[], wchar_t *wenvp) { (void)argc; @@ -107,7 +112,7 @@ extern "C" { #endif - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw) #else /* ANSI */ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw) @@ -124,83 +129,7 @@ } /* extern "C" */ #endif - /* end of SDL_PLATFORM_WIN32 and SDL_PLATFORM_GDK impls */ - - #elif defined(SDL_PLATFORM_WINRT) - - /* WinRT main based on SDL_winrt_main_NonXAML.cpp, placed in the public domain by David Ludwig 3/13/14 */ - - #include - - /* At least one file in any SDL/WinRT app appears to require compilation - with C++/CX, otherwise a Windows Metadata file won't get created, and - an APPX0702 build error can appear shortly after linking. - - The following set of preprocessor code forces this file to be compiled - as C++/CX, which appears to cause Visual C++ 2012's build tools to - create this .winmd file, and will help allow builds of SDL/WinRT apps - to proceed without error. - - If other files in an app's project enable C++/CX compilation, then it might - be possible for the .cpp file including SDL_main.h to be compiled without /ZW, - for Visual C++'s build tools to create a winmd file, and for the app to - build without APPX0702 errors. In this case, if - SDL_WINRT_METADATA_FILE_AVAILABLE is defined as a C/C++ macro, then - the #error (to force C++/CX compilation) will be disabled. - - Please note that /ZW can be specified on a file-by-file basis. To do this, - right click on the file in Visual C++, click Properties, then change the - setting through the dialog that comes up. - */ - #ifndef SDL_WINRT_METADATA_FILE_AVAILABLE - #if !defined(__cplusplus) || (!defined(__cplusplus_winrt) && _MSVC_LANG < 202002L) - #error The C++ file that includes SDL_main.h must be compiled as C++ code with /ZW, otherwise build errors due to missing .winmd files can occur. - #endif - #endif - - /* Prevent MSVC++ from warning about threading models when defining our - custom WinMain. The threading model will instead be set via a direct - call to Windows::Foundation::Initialize (rather than via an attributed - function). - - To note, this warning (C4447) does not seem to come up unless this file - is compiled with C++/CX enabled (via the /ZW compiler flag). - */ - #ifdef _MSC_VER - #pragma warning(disable : 4447) - /* Make sure the function to initialize the Windows Runtime gets linked in. */ - #pragma comment(lib, "runtimeobject.lib") - #endif - - #ifdef __cplusplus - extern "C" { - #endif - int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int) - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - #if _MSVC_LANG >= 202002L - int main(int argc, char** argv) { - return SDL_RunApp(argc, argv, SDL_main, NULL); - } - #endif - #ifdef __cplusplus - } /* extern "C" */ - #endif - - /* end of WinRT impl */ - - #elif defined(SDL_PLATFORM_NGAGE) - /* same typedef as in ngage SDKs e32def.h */ - typedef signed int TInt; - /* TODO: if it turns out that this only works when built as C++, - move SDL_PLATFORM_NGAGE into the C++ section in SDL_main.h */ - TInt E32Main() - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - - /* end of SDL_PLATFORM_NGAGE impl */ + /* end of SDL_PLATFORM_WINDOWS impls */ #else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ int main(int argc, char *argv[]) diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_messagebox.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_messagebox.h index c626b22..365ae36 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_messagebox.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_messagebox.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryMessagebox * - * Message box support routines. + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. */ #ifndef SDL_messagebox_h_ @@ -39,11 +50,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. + * Message box flags. * * If supported will display warning icon, etc. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxFlags; @@ -56,7 +67,7 @@ typedef Uint32 SDL_MessageBoxFlags; /** * SDL_MessageBoxButtonData flags. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxButtonFlags; @@ -66,7 +77,7 @@ typedef Uint32 SDL_MessageBoxButtonFlags; /** * Individual button data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxButtonData { @@ -78,7 +89,7 @@ typedef struct SDL_MessageBoxButtonData /** * RGB value used in a message box color scheme * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColor { @@ -96,23 +107,23 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX /**< Size of the colors array of SDL_MessageBoxColorScheme. */ + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** * A set of colors to use for message box dialogs * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** * MessageBox structure containing title, text, window, etc. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxData { @@ -154,14 +165,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowSimpleMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -193,17 +204,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData * to stderr if you can. * * \param flags an SDL_MessageBoxFlags value. - * \param title uTF-8 title text. - * \param message uTF-8 message text. + * \param title UTF-8 title text. + * \param message UTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_metal.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_metal.h index 7c9aece..14b1bc8 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_metal.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_metal.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,10 @@ * # CategoryMetal * * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. */ #ifndef SDL_metal_h_ @@ -39,7 +43,7 @@ extern "C" { /** * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_MetalView; @@ -61,7 +65,7 @@ typedef void *SDL_MetalView; * \param window the window. * \returns handle NSView or UIView. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_DestroyView * \sa SDL_Metal_GetLayer @@ -76,7 +80,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *windo * * \param view the SDL_MetalView object. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ @@ -88,7 +92,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); * \param view the SDL_MetalView object. * \returns a pointer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_misc.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_misc.h index 23317e0..3dd6fcd 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_misc.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_misc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -62,12 +62,12 @@ extern "C" { * * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mouse.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mouse.h index 90c8560..18856e2 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mouse.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mouse.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,36 @@ /** * # CategoryMouse * - * SDL mouse handling. + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. */ #ifndef SDL_mouse_h_ @@ -30,6 +59,7 @@ #include #include +#include #include #include @@ -46,7 +76,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MouseID; @@ -55,14 +85,14 @@ typedef Uint32 SDL_MouseID; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Cursor SDL_Cursor; /** * Cursor types for SDL_CreateSystemCursor(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemCursor { @@ -86,13 +116,13 @@ typedef enum SDL_SystemCursor SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ - SDL_NUM_SYSTEM_CURSORS + SDL_SYSTEM_CURSOR_COUNT } SDL_SystemCursor; /** * Scroll direction types for the Scroll event * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MouseWheelDirection { @@ -109,7 +139,7 @@ typedef enum SDL_MouseWheelDirection * - Button 4: Side mouse button 1 * - Button 5: Side mouse button 2 * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetMouseState * \sa SDL_GetGlobalMouseState @@ -123,12 +153,12 @@ typedef Uint32 SDL_MouseButtonFlags; #define SDL_BUTTON_X1 4 #define SDL_BUTTON_X2 5 -#define SDL_BUTTON(X) (1u << ((X)-1)) -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) /* Function prototypes */ @@ -136,13 +166,15 @@ typedef Uint32 SDL_MouseButtonFlags; /** * Return whether a mouse is currently connected. * - * \returns SDL_TRUE if a mouse is connected, SDL_FALSE otherwise. + * \returns true if a mouse is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); /** * Get a list of currently connected mice. @@ -158,7 +190,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseNameForID * \sa SDL_HasMouse @@ -174,7 +208,9 @@ extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count); * \returns the name of the selected mouse, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ @@ -185,26 +221,39 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta * * \returns the window with mouse focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); /** - * Retrieve the current state of the mouse. + * Query SDL's cache for the synchronous mouse button state and the + * window-relative SDL-cursor position. * - * The current button state is returned as a button bitmask, which can be - * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse cursor position relative to the focus window. You can pass NULL for - * either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x the x coordinate of the mouse cursor position relative to the - * focus window. - * \param y the y coordinate of the mouse cursor position relative to the - * focus window. - * \returns a 32-bit button bitmask of the current button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the focused window. + * + * In Relative Mode, the SDL-cursor's position usually contradicts the + * platform-cursor's position as manually calculated from + * SDL_GetGlobalMouseState() and SDL_GetWindowPosition. + * + * \param x a pointer to receive the SDL-cursor's x-position from the focused + * window's top left corner, can be NULL if unused. + * \param y a pointer to receive the SDL-cursor's y-position from the focused + * window's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState * \sa SDL_GetRelativeMouseState @@ -212,51 +261,74 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y); /** - * Get the current state of the mouse in relation to the desktop. + * Query the platform for the asynchronous mouse button state and the + * desktop-relative platform-cursor position. * - * This works similarly to SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if you - * need to track the mouse outside of a specific window and SDL_CaptureMouse() - * doesn't fit your needs. For example, it could be useful if you need to - * track the mouse while dragging a window, where coordinates relative to a - * window might not be in sync at all times. + * This function immediately queries the platform for the most recent + * asynchronous state, more costly than retrieving SDL's cached state in + * SDL_GetMouseState(). * - * Note: SDL_GetMouseState() returns the mouse position as SDL understands it - * from the last pump of the event queue. This function, however, queries the - * OS for the current mouse position, and as such, might be a slightly less - * efficient function. Unless you know what you're doing and have a good - * reason to use this function, you probably want SDL_GetMouseState() instead. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the desktop. * - * \param x filled in with the current X coord relative to the desktop; can be - * NULL. - * \param y filled in with the current Y coord relative to the desktop; can be - * NULL. - * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. + * In Relative Mode, the platform-cursor's position usually contradicts the + * SDL-cursor's position as manually calculated from SDL_GetMouseState() and + * SDL_GetWindowPosition. * - * \since This function is available since SDL 3.0.0. + * This function can be useful if you need to track the mouse outside of a + * specific window and SDL_CaptureMouse() doesn't fit your needs. For example, + * it could be useful if you need to track the mouse while dragging a window, + * where coordinates relative to a window might not be in sync at all times. + * + * \param x a pointer to receive the platform-cursor's x-position from the + * desktop's top left corner, can be NULL if unused. + * \param y a pointer to receive the platform-cursor's y-position from the + * desktop's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CaptureMouse * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y); /** - * Retrieve the relative state of the mouse. + * Query SDL's cache for the synchronous mouse button state and accumulated + * mouse delta since last call. * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x a pointer filled with the last recorded x coordinate of the mouse. - * \param y a pointer filled with the last recorded y coordinate of the mouse. - * \returns a 32-bit button bitmask of the relative button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y deltas accumulated since the last call to this function + * (or since event initialization). + * + * This function is useful for reducing overhead by processing relative mouse + * inputs in one go per-frame instead of individually per-event, at the + * expense of losing the order between events within the frame (e.g. quickly + * pressing and releasing a button within the same frame). + * + * \param x a pointer to receive the x mouse delta accumulated since last + * call, can be NULL if unused. + * \param y a pointer to receive the y mouse delta accumulated since last + * call, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y); @@ -275,7 +347,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float * \param x the x coordinate within the window. * \param y the y coordinate within the window. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseGlobal */ @@ -295,14 +369,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * * \param x the x coordinate. * \param y the y coordinate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseInWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); /** * Set relative mouse mode for a window. @@ -312,31 +388,39 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * report continuous relative mouse motion even if the mouse is at the edge of * the window. * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * * This function will flush any pending mouse motion for this window. * * \param window the window to change. - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); /** * Query whether relative mouse mode is enabled for a window. * * \param window the window to query. - * \returns SDL_TRUE if relative mode is enabled for a window or SDL_FALSE - * otherwise. + * \returns true if relative mode is enabled for a window or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); /** * Capture the mouse and to track input outside an SDL window. @@ -374,15 +458,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window * * app, you can disable auto capture by setting the * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); /** * Create a cursor using the specified bitmap data and mask (in MSB format). @@ -419,7 +505,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); * \returns a new cursor with the specified parameters on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateSystemCursor @@ -450,7 +538,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data, * \returns the new cursor on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCursor * \sa SDL_CreateSystemCursor @@ -468,7 +558,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyCursor */ @@ -483,14 +575,16 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * this is desired for any reason. * * \param cursor a cursor to make active. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); /** * Get the active cursor. @@ -500,7 +594,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); * * \returns the active cursor or NULL if there is no mouse. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetCursor */ @@ -515,7 +611,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void); * \returns the default cursor on success or NULL on failuree; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); @@ -527,7 +625,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); * * \param cursor the cursor to free. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateCursor @@ -538,41 +638,47 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); /** * Show the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_HideCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); /** * Hide the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); /** * Return whether the cursor is currently being shown. * - * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the - * cursor is hidden. + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideCursor * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mutex.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mutex.h index 3a7ce56..c88ec15 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mutex.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_mutex.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,84 +25,245 @@ /** * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. */ #include +#include #include +#include -/******************************************************************************/ -/* Enable thread safety attributes only with clang. +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Enable thread safety attributes, only with clang. + * * The attributes can be safely erased when compiling with other compilers. * * To enable analysis, set these environment variables before running cmake: - * export CC=clang - * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` */ -#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ - defined(__clang__) && (!defined(SWIG)) +#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) + +#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG)) #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) #else #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ #endif +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SCOPED_CAPABILITY \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PT_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_BEFORE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_AFTER(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_GENERIC(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE_SHARED(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_EXCLUDES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_SHARED_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RETURN_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) @@ -130,7 +291,7 @@ extern "C" { * * https://en.wikipedia.org/wiki/Mutex * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Mutex SDL_Mutex; @@ -147,7 +308,7 @@ typedef struct SDL_Mutex SDL_Mutex; * \returns the initialized and unlocked mutex or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyMutex * \sa SDL_LockMutex @@ -173,7 +334,7 @@ extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); * * \param mutex the mutex to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockMutex * \sa SDL_UnlockMutex @@ -184,22 +345,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * Try to lock a mutex without blocking. * * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns SDL_FALSE immediately. + * this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. * - * This function returns SDL_TRUE if passed a NULL mutex. + * This function returns true if passed a NULL mutex. * * \param mutex the mutex to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the mutex would block. + * \returns true on success, false if the mutex would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_UnlockMutex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); /** * Unlock the mutex. @@ -213,7 +374,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ * * \param mutex the mutex to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_TryLockMutex @@ -231,7 +392,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m * * \param mutex the mutex to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateMutex */ @@ -261,7 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); * about how threads are scheduled and when they can be recursively locked. * These are documented in the other rwlock functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_RWLock SDL_RWLock; @@ -296,7 +457,7 @@ typedef struct SDL_RWLock SDL_RWLock; * \returns the initialized and unlocked read/write lock or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRWLock * \sa SDL_LockRWLockForReading @@ -336,7 +497,7 @@ extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading @@ -367,7 +528,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting @@ -379,7 +540,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Try to lock a read/write lock _for reading_ without blocking. * * This works just like SDL_LockRWLockForReading(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need access to a resource but don't want to * wait for it, and will return to it to try again later. @@ -387,24 +548,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Trying to lock for read-only access can succeed if other threads are * holding read-only locks, as this won't prevent access. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); /** * Try to lock a read/write lock _for writing_ without blocking. * * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. @@ -417,18 +578,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwl * read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock before requesting a write lock. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); /** * Unlock the read/write lock. @@ -446,7 +607,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwl * * \param rwlock the rwlock to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_LockRWLockForWriting @@ -466,7 +627,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS * * \param rwlock the rwlock to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRWLock */ @@ -492,7 +653,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); * * https://en.wikipedia.org/wiki/Semaphore_(programming) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Semaphore SDL_Semaphore; @@ -509,7 +670,7 @@ typedef struct SDL_Semaphore SDL_Semaphore; * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySemaphore * \sa SDL_SignalSemaphore @@ -528,7 +689,7 @@ extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_v * * \param sem the semaphore to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSemaphore */ @@ -546,7 +707,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * * \param sem the semaphore wait on. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore @@ -560,18 +721,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * This function checks to see if the semaphore pointed to by `sem` has a * positive value and atomically decrements the semaphore value if it does. If * the semaphore doesn't have a positive value, the function immediately - * returns SDL_FALSE. + * returns false. * * \param sem the semaphore to wait on. - * \returns SDL_TRUE if the wait succeeds, SDL_FALSE if the wait would block. + * \returns true if the wait succeeds, false if the wait would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. @@ -583,22 +744,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to wait on. * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the wait succeeds or SDL_FALSE if the wait times out. + * \returns true if the wait succeeds or false if the wait times out. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); /** * Atomically increment a semaphore's value and wake waiting threads. * * \param sem the semaphore to increment. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore @@ -612,7 +773,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to query. * \returns the current value of the semaphore. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); @@ -635,7 +796,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); * * https://en.wikipedia.org/wiki/Condition_variable * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Condition SDL_Condition; @@ -645,7 +806,7 @@ typedef struct SDL_Condition SDL_Condition; * \returns a new condition variable or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -660,7 +821,7 @@ extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); * * \param cond the condition variable to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCondition */ @@ -673,7 +834,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_WaitCondition @@ -688,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalCondition * \sa SDL_WaitCondition @@ -716,7 +877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -741,22 +902,167 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mute * \param mutex the mutex used to coordinate thread access. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the condition variable is signaled, SDL_FALSE if the - * condition is not signaled in the allotted time. + * \returns true if the condition variable is signaled, false if the condition + * is not signaled in the allotted time. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition * \sa SDL_WaitCondition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, SDL_Mutex *mutex, Sint32 timeoutMS); /* @} *//* Condition variable functions */ +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * DoQuitTasks(); + * SDL_SetInitialized(&init, false); + * } + * ``` + * + * Note that this doesn't protect any resources created during initialization, + * or guarantee that nobody is using those resources during cleanup. You + * should use other mechanisms to protect those, if that's a concern for your + * code. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_oldnames.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_oldnames.h index 02c881c..c93607e 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_oldnames.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_oldnames.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -38,11 +38,14 @@ #ifdef SDL_ENABLE_OLD_NAMES /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer #define SDL_AtomicLock SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_UnlockSpinlock #define SDL_atomic_t SDL_AtomicInt @@ -74,6 +77,7 @@ #define SDL_NewAudioStream SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -166,14 +170,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -193,7 +196,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -304,6 +307,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -419,9 +424,15 @@ #define SDL_LogSetAllPriority SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK #define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT @@ -558,6 +569,7 @@ #define SDL_WriteLE64 SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -580,7 +592,12 @@ #define SDL_SensorUpdate SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE false #define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtok_r /* ##SDL_surface.h */ @@ -623,14 +640,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iPhoneSetEventPump SDL_SetiOSEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_CleanupTLS #define SDL_TLSGet SDL_GetTLS #define SDL_TLSSet SDL_SetTLS @@ -645,6 +661,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint @@ -661,11 +681,14 @@ #elif !defined(SDL_DISABLE_OLD_NAMES) /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer #define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock #define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt @@ -697,6 +720,7 @@ #define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -789,14 +813,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_WINDOWEVENT_RESTORED_renamed_SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_WINDOWEVENT_SHOWN_renamed_SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_WINDOWEVENT_TAKE_FOCUS_renamed_SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_eventaction_renamed_SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_CONTROLLER_AXIS_RIGHTX_renamed_SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_CONTROLLER_AXIS_RIGHTY_renamed_SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_CONTROLLER_AXIS_TRIGGERLEFT_renamed_SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -816,7 +839,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_CONTROLLER_BUTTON_INVALID_renamed_SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_CONTROLLER_BUTTON_LEFTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_CONTROLLER_BUTTON_LEFTSTICK_renamed_SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_CONTROLLER_BUTTON_MISC1_renamed_SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_CONTROLLER_BUTTON_PADDLE1_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_CONTROLLER_BUTTON_PADDLE2_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -928,6 +951,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE_renamed_SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_LINUX_DIGITAL_HATS_renamed_SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_LINUX_HAT_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_LINUX_JOYSTICK_CLASSIC_renamed_SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -1043,9 +1068,15 @@ #define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK #define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT @@ -1182,6 +1213,7 @@ #define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -1204,7 +1236,12 @@ #define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false #define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r /* ##SDL_surface.h */ @@ -1247,14 +1284,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_WinRTGetDeviceFamily_renamed_SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPathUTF8_renamed_SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback #define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS #define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS #define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS @@ -1269,6 +1305,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DeleteContext_renamed_SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLattr_renamed_SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLcontextFlag_renamed_SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLcontextReleaseFlag_renamed_SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLprofile_renamed_SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestDisplayMode_renamed_SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetDisplayOrientation_renamed_SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengl.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengl.h index 6bdcbe0..d1b8b02 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengl.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -783,6 +783,7 @@ typedef double GLclampd; /* double precision float in [0,1] */ * Miscellaneous */ +#ifndef SDL_OPENGL_1_NO_PROTOTYPES GLAPI void GLAPIENTRY glClearIndex( GLfloat c ); GLAPI void GLAPIENTRY glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); @@ -1480,6 +1481,706 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); + +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); + +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); + +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); + +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); + +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); + +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); + +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); + +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); + +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); + +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); + +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); + +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); + +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); + +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); + +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); + +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); + +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); + + +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + + +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); + +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); + +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); + + +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ + + +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); + +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); + +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); + +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); + +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); + +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); + + +/* + * Depth Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARDEPTHPROC) ( GLclampd depth ); + +typedef void (APIENTRYP PFNGLDEPTHFUNCPROC) ( GLenum func ); + +typedef void (APIENTRYP PFNGLDEPTHMASKPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLDEPTHRANGEPROC) ( GLclampd near_val, GLclampd far_val ); + + +/* + * Accumulation Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARACCUMPROC) ( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha ); + +typedef void (APIENTRYP PFNGLACCUMPROC) ( GLenum op, GLfloat value ); + + +/* + * Transformation + */ + +typedef void (APIENTRYP PFNGLMATRIXMODEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLORTHOPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLFRUSTUMPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLVIEWPORTPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height ); + +typedef void (APIENTRYP PFNGLPUSHMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLPOPMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADIDENTITYPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLLOADMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLMULTMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLMULTMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLROTATEDPROC) ( GLdouble angle, + GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLROTATEFPROC) ( GLfloat angle, + GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLSCALEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLSCALEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLTRANSLATEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLTRANSLATEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + + +/* + * Display Lists + */ + +typedef GLboolean (APIENTRYP PFNGLISLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLDELETELISTSPROC) ( GLuint list, GLsizei range ); + +typedef GLuint (APIENTRYP PFNGLGENLISTSPROC) ( GLsizei range ); + +typedef void (APIENTRYP PFNGLNEWLISTPROC) ( GLuint list, GLenum mode ); + +typedef void (APIENTRYP PFNGLENDLISTPROC) ( void ); + +typedef void (APIENTRYP PFNGLCALLLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLCALLLISTSPROC) ( GLsizei n, GLenum type, + const GLvoid *lists ); + +typedef void (APIENTRYP PFNGLLISTBASEPROC) ( GLuint base ); + + +/* + * Drawing Functions + */ + +typedef void (APIENTRYP PFNGLBEGINPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENDPROC) ( void ); + + +typedef void (APIENTRYP PFNGLVERTEX2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLVERTEX2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLVERTEX2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLVERTEX2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLVERTEX3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLVERTEX3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLVERTEX3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLVERTEX3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLVERTEX4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLVERTEX4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLVERTEX4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLVERTEX4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLVERTEX2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLNORMAL3BPROC) ( GLbyte nx, GLbyte ny, GLbyte nz ); +typedef void (APIENTRYP PFNGLNORMAL3DPROC) ( GLdouble nx, GLdouble ny, GLdouble nz ); +typedef void (APIENTRYP PFNGLNORMAL3FPROC) ( GLfloat nx, GLfloat ny, GLfloat nz ); +typedef void (APIENTRYP PFNGLNORMAL3IPROC) ( GLint nx, GLint ny, GLint nz ); +typedef void (APIENTRYP PFNGLNORMAL3SPROC) ( GLshort nx, GLshort ny, GLshort nz ); + +typedef void (APIENTRYP PFNGLNORMAL3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLNORMAL3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLNORMAL3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLNORMAL3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLNORMAL3SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLINDEXDPROC) ( GLdouble c ); +typedef void (APIENTRYP PFNGLINDEXFPROC) ( GLfloat c ); +typedef void (APIENTRYP PFNGLINDEXIPROC) ( GLint c ); +typedef void (APIENTRYP PFNGLINDEXSPROC) ( GLshort c ); +typedef void (APIENTRYP PFNGLINDEXUBPROC) ( GLubyte c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLINDEXDVPROC) ( const GLdouble *c ); +typedef void (APIENTRYP PFNGLINDEXFVPROC) ( const GLfloat *c ); +typedef void (APIENTRYP PFNGLINDEXIVPROC) ( const GLint *c ); +typedef void (APIENTRYP PFNGLINDEXSVPROC) ( const GLshort *c ); +typedef void (APIENTRYP PFNGLINDEXUBVPROC) ( const GLubyte *c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLCOLOR3BPROC) ( GLbyte red, GLbyte green, GLbyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3DPROC) ( GLdouble red, GLdouble green, GLdouble blue ); +typedef void (APIENTRYP PFNGLCOLOR3FPROC) ( GLfloat red, GLfloat green, GLfloat blue ); +typedef void (APIENTRYP PFNGLCOLOR3IPROC) ( GLint red, GLint green, GLint blue ); +typedef void (APIENTRYP PFNGLCOLOR3SPROC) ( GLshort red, GLshort green, GLshort blue ); +typedef void (APIENTRYP PFNGLCOLOR3UBPROC) ( GLubyte red, GLubyte green, GLubyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3UIPROC) ( GLuint red, GLuint green, GLuint blue ); +typedef void (APIENTRYP PFNGLCOLOR3USPROC) ( GLushort red, GLushort green, GLushort blue ); + +typedef void (APIENTRYP PFNGLCOLOR4BPROC) ( GLbyte red, GLbyte green, + GLbyte blue, GLbyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4DPROC) ( GLdouble red, GLdouble green, + GLdouble blue, GLdouble alpha ); +typedef void (APIENTRYP PFNGLCOLOR4FPROC) ( GLfloat red, GLfloat green, + GLfloat blue, GLfloat alpha ); +typedef void (APIENTRYP PFNGLCOLOR4IPROC) ( GLint red, GLint green, + GLint blue, GLint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4SPROC) ( GLshort red, GLshort green, + GLshort blue, GLshort alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UBPROC) ( GLubyte red, GLubyte green, + GLubyte blue, GLubyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UIPROC) ( GLuint red, GLuint green, + GLuint blue, GLuint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4USPROC) ( GLushort red, GLushort green, + GLushort blue, GLushort alpha ); + + +typedef void (APIENTRYP PFNGLCOLOR3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR3SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR3UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR3USVPROC) ( const GLushort *v ); + +typedef void (APIENTRYP PFNGLCOLOR4BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR4SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR4UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR4USVPROC) ( const GLushort *v ); + + +typedef void (APIENTRYP PFNGLTEXCOORD1DPROC) ( GLdouble s ); +typedef void (APIENTRYP PFNGLTEXCOORD1FPROC) ( GLfloat s ); +typedef void (APIENTRYP PFNGLTEXCOORD1IPROC) ( GLint s ); +typedef void (APIENTRYP PFNGLTEXCOORD1SPROC) ( GLshort s ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DPROC) ( GLdouble s, GLdouble t ); +typedef void (APIENTRYP PFNGLTEXCOORD2FPROC) ( GLfloat s, GLfloat t ); +typedef void (APIENTRYP PFNGLTEXCOORD2IPROC) ( GLint s, GLint t ); +typedef void (APIENTRYP PFNGLTEXCOORD2SPROC) ( GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DPROC) ( GLdouble s, GLdouble t, GLdouble r ); +typedef void (APIENTRYP PFNGLTEXCOORD3FPROC) ( GLfloat s, GLfloat t, GLfloat r ); +typedef void (APIENTRYP PFNGLTEXCOORD3IPROC) ( GLint s, GLint t, GLint r ); +typedef void (APIENTRYP PFNGLTEXCOORD3SPROC) ( GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DPROC) ( GLdouble s, GLdouble t, GLdouble r, GLdouble q ); +typedef void (APIENTRYP PFNGLTEXCOORD4FPROC) ( GLfloat s, GLfloat t, GLfloat r, GLfloat q ); +typedef void (APIENTRYP PFNGLTEXCOORD4IPROC) ( GLint s, GLint t, GLint r, GLint q ); +typedef void (APIENTRYP PFNGLTEXCOORD4SPROC) ( GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLTEXCOORD1DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRASTERPOS2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLRASTERPOS2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLRASTERPOS2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLRASTERPOS2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLRASTERPOS3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLRASTERPOS3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLRASTERPOS3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLRASTERPOS4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLRASTERPOS4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLRASTERPOS4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLRASTERPOS2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRECTDPROC) ( GLdouble x1, GLdouble y1, GLdouble x2, GLdouble y2 ); +typedef void (APIENTRYP PFNGLRECTFPROC) ( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ); +typedef void (APIENTRYP PFNGLRECTIPROC) ( GLint x1, GLint y1, GLint x2, GLint y2 ); +typedef void (APIENTRYP PFNGLRECTSPROC) ( GLshort x1, GLshort y1, GLshort x2, GLshort y2 ); + + +typedef void (APIENTRYP PFNGLRECTDVPROC) ( const GLdouble *v1, const GLdouble *v2 ); +typedef void (APIENTRYP PFNGLRECTFVPROC) ( const GLfloat *v1, const GLfloat *v2 ); +typedef void (APIENTRYP PFNGLRECTIVPROC) ( const GLint *v1, const GLint *v2 ); +typedef void (APIENTRYP PFNGLRECTSVPROC) ( const GLshort *v1, const GLshort *v2 ); + + +/* + * Vertex Arrays (1.1) + */ + +typedef void (APIENTRYP PFNGLVERTEXPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLNORMALPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLCOLORPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLINDEXPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLTEXCOORDPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPOINTERPROC) ( GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLGETPOINTERVPROC) ( GLenum pname, GLvoid **params ); + +typedef void (APIENTRYP PFNGLARRAYELEMENTPROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLDRAWARRAYSPROC) ( GLenum mode, GLint first, GLsizei count ); + +typedef void (APIENTRYP PFNGLDRAWELEMENTSPROC) ( GLenum mode, GLsizei count, + GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLINTERLEAVEDARRAYSPROC) ( GLenum format, GLsizei stride, + const GLvoid *pointer ); + +/* + * Lighting + */ + +typedef void (APIENTRYP PFNGLSHADEMODELPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLLIGHTFPROC) ( GLenum light, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTIPROC) ( GLenum light, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTFVPROC) ( GLenum light, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTIVPROC) ( GLenum light, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETLIGHTFVPROC) ( GLenum light, GLenum pname, + GLfloat *params ); +typedef void (APIENTRYP PFNGLGETLIGHTIVPROC) ( GLenum light, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLLIGHTMODELFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTMODELIPROC) ( GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTMODELFVPROC) ( GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTMODELIVPROC) ( GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLMATERIALFPROC) ( GLenum face, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLMATERIALIPROC) ( GLenum face, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLMATERIALFVPROC) ( GLenum face, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLMATERIALIVPROC) ( GLenum face, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETMATERIALFVPROC) ( GLenum face, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETMATERIALIVPROC) ( GLenum face, GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLCOLORMATERIALPROC) ( GLenum face, GLenum mode ); + + +/* + * Raster functions + */ + +typedef void (APIENTRYP PFNGLPIXELZOOMPROC) ( GLfloat xfactor, GLfloat yfactor ); + +typedef void (APIENTRYP PFNGLPIXELSTOREFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELSTOREIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELTRANSFERFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELTRANSFERIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELMAPFVPROC) ( GLenum map, GLsizei mapsize, + const GLfloat *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUIVPROC) ( GLenum map, GLsizei mapsize, + const GLuint *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUSVPROC) ( GLenum map, GLsizei mapsize, + const GLushort *values ); + +typedef void (APIENTRYP PFNGLGETPIXELMAPFVPROC) ( GLenum map, GLfloat *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUIVPROC) ( GLenum map, GLuint *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUSVPROC) ( GLenum map, GLushort *values ); + +typedef void (APIENTRYP PFNGLBITMAPPROC) ( GLsizei width, GLsizei height, + GLfloat xorig, GLfloat yorig, + GLfloat xmove, GLfloat ymove, + const GLubyte *bitmap ); + +typedef void (APIENTRYP PFNGLREADPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLDRAWPIXELSPROC) ( GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLCOPYPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum type ); + +/* + * Stenciling + */ + +typedef void (APIENTRYP PFNGLSTENCILFUNCPROC) ( GLenum func, GLint ref, GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILOPPROC) ( GLenum fail, GLenum zfail, GLenum zpass ); + +typedef void (APIENTRYP PFNGLCLEARSTENCILPROC) ( GLint s ); + + + +/* + * Texture mapping + */ + +typedef void (APIENTRYP PFNGLTEXGENDPROC) ( GLenum coord, GLenum pname, GLdouble param ); +typedef void (APIENTRYP PFNGLTEXGENFPROC) ( GLenum coord, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXGENIPROC) ( GLenum coord, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXGENDVPROC) ( GLenum coord, GLenum pname, const GLdouble *params ); +typedef void (APIENTRYP PFNGLTEXGENFVPROC) ( GLenum coord, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXGENIVPROC) ( GLenum coord, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXGENDVPROC) ( GLenum coord, GLenum pname, GLdouble *params ); +typedef void (APIENTRYP PFNGLGETTEXGENFVPROC) ( GLenum coord, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXGENIVPROC) ( GLenum coord, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXENVFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXENVIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXENVFVPROC) ( GLenum target, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXENVIVPROC) ( GLenum target, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXENVFVPROC) ( GLenum target, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXENVIVPROC) ( GLenum target, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXPARAMETERFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXPARAMETERFVPROC) ( GLenum target, + GLenum pname, GLfloat *params); +typedef void (APIENTRYP PFNGLGETTEXPARAMETERIVPROC) ( GLenum target, + GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERFVPROC) ( GLenum target, GLint level, + GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERIVPROC) ( GLenum target, GLint level, + GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLint border, GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLGETTEXIMAGEPROC) ( GLenum target, GLint level, + GLenum format, GLenum type, + GLvoid *pixels ); + + +/* 1.1 functions */ + +typedef void (APIENTRYP PFNGLGENTEXTURESPROC) ( GLsizei n, GLuint *textures ); + +typedef void (APIENTRYP PFNGLDELETETEXTURESPROC) ( GLsizei n, const GLuint *textures); + +typedef void (APIENTRYP PFNGLBINDTEXTUREPROC) ( GLenum target, GLuint texture ); + +typedef void (APIENTRYP PFNGLPRIORITIZETEXTURESPROC) ( GLsizei n, + const GLuint *textures, + const GLclampf *priorities ); + +typedef GLboolean (APIENTRYP PFNGLARETEXTURESRESIDENTPROC) ( GLsizei n, + const GLuint *textures, + GLboolean *residences ); + +typedef GLboolean (APIENTRYP PFNGLISTEXTUREPROC) ( GLuint texture ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, + GLsizei width, GLenum format, + GLenum type, const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLsizei height, + GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint x, GLint y, + GLsizei width ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint x, GLint y, + GLsizei width, GLsizei height ); + + +/* + * Evaluators + */ + +typedef void (APIENTRYP PFNGLMAP1DPROC) ( GLenum target, GLdouble u1, GLdouble u2, + GLint stride, + GLint order, const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP1FPROC) ( GLenum target, GLfloat u1, GLfloat u2, + GLint stride, + GLint order, const GLfloat *points ); + +typedef void (APIENTRYP PFNGLMAP2DPROC) ( GLenum target, + GLdouble u1, GLdouble u2, GLint ustride, GLint uorder, + GLdouble v1, GLdouble v2, GLint vstride, GLint vorder, + const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP2FPROC) ( GLenum target, + GLfloat u1, GLfloat u2, GLint ustride, GLint uorder, + GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, + const GLfloat *points ); + +typedef void (APIENTRYP PFNGLGETMAPDVPROC) ( GLenum target, GLenum query, GLdouble *v ); +typedef void (APIENTRYP PFNGLGETMAPFVPROC) ( GLenum target, GLenum query, GLfloat *v ); +typedef void (APIENTRYP PFNGLGETMAPIVPROC) ( GLenum target, GLenum query, GLint *v ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DPROC) ( GLdouble u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FPROC) ( GLfloat u ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DPROC) ( GLdouble u, GLdouble v ); +typedef void (APIENTRYP PFNGLEVALCOORD2FPROC) ( GLfloat u, GLfloat v ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD2FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLMAPGRID1DPROC) ( GLint un, GLdouble u1, GLdouble u2 ); +typedef void (APIENTRYP PFNGLMAPGRID1FPROC) ( GLint un, GLfloat u1, GLfloat u2 ); + +typedef void (APIENTRYP PFNGLMAPGRID2DPROC) ( GLint un, GLdouble u1, GLdouble u2, + GLint vn, GLdouble v1, GLdouble v2 ); +typedef void (APIENTRYP PFNGLMAPGRID2FPROC) ( GLint un, GLfloat u1, GLfloat u2, + GLint vn, GLfloat v1, GLfloat v2 ); + +typedef void (APIENTRYP PFNGLEVALPOINT1PROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLEVALPOINT2PROC) ( GLint i, GLint j ); + +typedef void (APIENTRYP PFNGLEVALMESH1PROC) ( GLenum mode, GLint i1, GLint i2 ); + +typedef void (APIENTRYP PFNGLEVALMESH2PROC) ( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + + +/* + * Fog + */ + +typedef void (APIENTRYP PFNGLFOGFPROC) ( GLenum pname, GLfloat param ); + +typedef void (APIENTRYP PFNGLFOGIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLFOGFVPROC) ( GLenum pname, const GLfloat *params ); + +typedef void (APIENTRYP PFNGLFOGIVPROC) ( GLenum pname, const GLint *params ); + + +/* + * Selection and Feedback + */ + +typedef void (APIENTRYP PFNGLFEEDBACKBUFFERPROC) ( GLsizei size, GLenum type, GLfloat *buffer ); + +typedef void (APIENTRYP PFNGLPASSTHROUGHPROC) ( GLfloat token ); + +typedef void (APIENTRYP PFNGLSELECTBUFFERPROC) ( GLsizei size, GLuint *buffer ); + +typedef void (APIENTRYP PFNGLINITNAMESPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPUSHNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPOPNAMEPROC) ( void ); +#endif /* @@ -1528,6 +2229,8 @@ GLAPI void GLAPIENTRY glPopName( void ); #define GL_MAX_3D_TEXTURE_SIZE 0x8073 #define GL_TEXTURE_BINDING_3D 0x806A +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); @@ -1551,6 +2254,34 @@ GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, GLint y, GLsizei width, GLsizei height ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) ( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif + typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); @@ -1638,6 +2369,8 @@ typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, #define GL_BLEND_COLOR 0x8005 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, GLsizei width, GLenum format, GLenum type, const GLvoid *table ); @@ -1746,6 +2479,119 @@ GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +typedef void (APIENTRYP PFNGLCOLORSUBTABLEPROC) ( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERIVPROC) (GLenum target, GLenum pname, + const GLint *params); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERFVPROC) (GLenum target, GLenum pname, + const GLfloat *params); + +typedef void (APIENTRYP PFNGLCOPYCOLORSUBTABLEPROC) ( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLBLENDEQUATIONPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLBLENDCOLORPROC) ( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLHISTOGRAMPROC) ( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETHISTOGRAMPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLMINMAXPROC) ( GLenum target, GLenum internalformat, + GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETMINMAXPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETMINMAXPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFPROC) ( GLenum target, GLenum pname, + GLfloat params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIPROC) ( GLenum target, GLenum pname, + GLint params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLSEPARABLEFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +typedef void (APIENTRYP PFNGLGETSEPARABLEFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif + @@ -1858,6 +2704,8 @@ GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, /* texture_border_clamp */ #define GL_CLAMP_TO_BORDER 0x812D +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTexture( GLenum texture ); GLAPI void GLAPIENTRY glClientActiveTexture( GLenum texture ); @@ -1951,6 +2799,104 @@ GLAPI void GLAPIENTRY glMultTransposeMatrixf( const GLfloat m[16] ); GLAPI void GLAPIENTRY glSampleCoverage( GLclampf value, GLboolean invert ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE1DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE2DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE3DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) ( GLenum target, GLint lod, GLvoid *img ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DPROC) ( GLenum target, GLdouble s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FPROC) ( GLenum target, GLfloat s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IPROC) ( GLenum target, GLint s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SPROC) ( GLenum target, GLshort s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DPROC) ( GLenum target, GLdouble s, GLdouble t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FPROC) ( GLenum target, GLfloat s, GLfloat t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IPROC) ( GLenum target, GLint s, GLint t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SPROC) ( GLenum target, GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IPROC) ( GLenum target, GLint s, GLint t, GLint r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IPROC) ( GLenum target, GLint s, GLint t, GLint r, GLint q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVPROC) ( GLenum target, const GLshort *v ); + + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) ( GLclampf value, GLboolean invert ); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) (GLenum texture); typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) (GLclampf value, GLboolean invert); @@ -2006,6 +2952,8 @@ typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) (GLenum target, GLint le #define GL_CLIENT_ACTIVE_TEXTURE_ARB 0x84E1 #define GL_MAX_TEXTURE_UNITS_ARB 0x84E2 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glClientActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glMultiTexCoord1dARB(GLenum target, GLdouble s); @@ -2041,6 +2989,46 @@ GLAPI void GLAPIENTRY glMultiTexCoord4ivARB(GLenum target, const GLint *v); GLAPI void GLAPIENTRY glMultiTexCoord4sARB(GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); GLAPI void GLAPIENTRY glMultiTexCoord4svARB(GLenum target, const GLshort *v); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FARBPROC) (GLenum target, GLfloat s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IARBPROC) (GLenum target, GLint s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SARBPROC) (GLenum target, GLshort s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DARBPROC) (GLenum target, GLdouble s, GLdouble t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FARBPROC) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IARBPROC) (GLenum target, GLint s, GLint t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SARBPROC) (GLenum target, GLshort s, GLshort t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IARBPROC) (GLenum target, GLint s, GLint t, GLint r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IARBPROC) (GLenum target, GLint s, GLint t, GLint r, GLint q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLshort *v); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles.h index bde4d74..4fb9a4b 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles2.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles2.h index ba19601..365898a 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles2.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_opengles2.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pen.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pen.h index cda4f0f..5182eeb 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pen.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pen.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -39,7 +39,9 @@ #ifndef SDL_pen_h_ #define SDL_pen_h_ -#include +#include +#include +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -55,24 +57,39 @@ extern "C" { * consistent as long as SDL can recognize a tool to be the same pen; but if a * pen physically leaves the area and returns, it might get a new ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenID; +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + /** * Pen input flags, as reported by various pen events' `pen_state` field. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenInputFlags; -#define SDL_PEN_INPUT_DOWN (1u << 0) /**< & to see if pen is pressed down */ -#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< & to see if button 1 is pressed */ -#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< & to see if button 2 is pressed */ -#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< & to see if button 3 is pressed */ -#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< & to see if button 4 is pressed */ -#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< & to see if button 5 is pressed */ -#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< & to see if eraser tip is used */ + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ /** * Pen axis indices. @@ -87,20 +104,18 @@ typedef Uint32 SDL_PenInputFlags; * * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PenAxis { SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ - SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). - The physical max/min tilt may be smaller than -90.0 / 90.0, check SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). - The physical max/min tilt may be smaller than -90.0 / 90.0 check SDL_PenCapabilityInfo */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ - SDL_PEN_NUM_AXES /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ } SDL_PenAxis; /* Ends C function definitions when using C++ */ @@ -110,4 +125,3 @@ typedef enum SDL_PenAxis #endif /* SDL_pen_h_ */ -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pixels.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pixels.h index 3825dd5..b6f38ac 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pixels.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_pixels.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,59 @@ /** * # CategoryPixels * - * Pixel management. + * SDL offers facilities for pixel management. + * + * Largely these facilities deal with pixel _format_: what does this set of + * bits represent? + * + * If you mostly want to think of a pixel as some combination of red, green, + * blue, and maybe alpha intensities, this is all pretty straightforward, and + * in many cases, is enough information to build a perfectly fine game. + * + * However, the actual definition of a pixel is more complex than that: + * + * Pixels are a representation of a color in a particular color space. + * + * The first characteristic of a color space is the color type. SDL + * understands two different color types, RGB and YCbCr, or in SDL also + * referred to as YUV. + * + * RGB colors consist of red, green, and blue channels of color that are added + * together to represent the colors we see on the screen. + * + * https://en.wikipedia.org/wiki/RGB_color_model + * + * YCbCr colors represent colors as a Y luma brightness component and red and + * blue chroma color offsets. This color representation takes advantage of the + * fact that the human eye is more sensitive to brightness than the color in + * an image. The Cb and Cr components are often compressed and have lower + * resolution than the luma component. + * + * https://en.wikipedia.org/wiki/YCbCr + * + * When the color information in YCbCr is compressed, the Y pixels are left at + * full resolution and each Cr and Cb pixel represents an average of the color + * information in a block of Y pixels. The chroma location determines where in + * that block of pixels the color information is coming from. + * + * The color range defines how much of the pixel to use when converting a + * pixel into a color on the display. When the full color range is used, the + * entire numeric range of the pixel bits is significant. When narrow color + * range is used, for historical reasons, the pixel uses only a portion of the + * numeric range to represent colors. + * + * The color primaries and white point are a definition of the colors in the + * color space relative to the standard XYZ color space. + * + * https://en.wikipedia.org/wiki/CIE_1931_color_space + * + * The transfer characteristic, or opto-electrical transfer function (OETF), + * is the way a color is converted from mathematically linear space into a + * non-linear output signals. + * + * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics + * + * The matrix coefficients are used to convert between YCbCr and RGB colors. */ #ifndef SDL_pixels_h_ @@ -41,22 +93,44 @@ extern "C" { /** * A fully opaque 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_TRANSPARENT */ #define SDL_ALPHA_OPAQUE 255 +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + /** * A fully transparent 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_OPAQUE */ #define SDL_ALPHA_TRANSPARENT 0 -/** Pixel type. */ +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, @@ -75,7 +149,11 @@ typedef enum SDL_PixelType SDL_PIXELTYPE_INDEX2 } SDL_PixelType; -/** Bitmap pixel order, high bit -> low bit. */ +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, @@ -83,7 +161,11 @@ typedef enum SDL_BitmapOrder SDL_BITMAPORDER_1234 } SDL_BitmapOrder; -/** Packed component order, high bit -> low bit. */ +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, @@ -97,7 +179,11 @@ typedef enum SDL_PackedOrder SDL_PACKEDORDER_BGRA } SDL_PackedOrder; -/** Array component order, low byte -> high byte. */ +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, @@ -109,7 +195,11 @@ typedef enum SDL_ArrayOrder SDL_ARRAYORDER_ABGR } SDL_ArrayOrder; -/** Packed component layout. */ +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, @@ -123,25 +213,172 @@ typedef enum SDL_PackedLayout SDL_PACKEDLAYOUT_1010102 } SDL_PackedLayout; +/** + * A macro for defining custom FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_YV12 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') + * ``` + * + * \param A the first character of the FourCC code. + * \param B the second character of the FourCC code. + * \param C the third character of the FourCC code. + * \param D the fourth character of the FourCC code. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) +/** + * A macro for defining custom non-FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) + * ``` + * + * \param type the type of the new format, probably a SDL_PixelType value. + * \param order the order of the new format, probably a SDL_BitmapOrder, + * SDL_PackedOrder, or SDL_ArrayOrder value. + * \param layout the layout of the new format, probably an SDL_PackedLayout + * value or zero. + * \param bits the number of bits per pixel of the new format. + * \param bytes the number of bytes per pixel of the new format. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ ((bits) << 8) | ((bytes) << 0)) -#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) -#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) -#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) -#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) -#define SDL_BITSPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU) || \ - ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF)) +/** + * A macro to retrieve the flags of an SDL_PixelFormat. + * + * This macro is generally not needed directly by an app, which should use + * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. + * + * \param format an SDL_PixelFormat to check. + * \returns the flags of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) +/** + * A macro to retrieve the type of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PixelType enumeration. + * + * \param format an SDL_PixelFormat to check. + * \returns the type of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) + +/** + * A macro to retrieve the order of an SDL_PixelFormat. + * + * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or + * SDL_ArrayOrder enumerations, depending on the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the order of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) + +/** + * A macro to retrieve the layout of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PackedLayout enumeration, or zero if a + * layout doesn't make sense for the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the layout of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) + +/** + * A macro to determine an SDL_PixelFormat's bits per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats will report zero here, as it rarely makes sense to measure + * them per-pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bits-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTESPERPIXEL + */ +#define SDL_BITSPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) + +/** + * A macro to determine an SDL_PixelFormat's bytes per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats do their best here, but many of them don't have a meaningful + * measurement of bytes per pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bytes-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BITSPERPIXEL + */ +#define SDL_BYTESPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? \ + ((((format) == SDL_PIXELFORMAT_YUY2) || \ + ((format) == SDL_PIXELFORMAT_UYVY) || \ + ((format) == SDL_PIXELFORMAT_YVYU) || \ + ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) + + +/** + * A macro to determine if an SDL_PixelFormat is an indexed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is indexed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -149,12 +386,38 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) +/** + * A macro to determine if an SDL_PixelFormat is a packed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is packed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_PACKED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) +/** + * A macro to determine if an SDL_PixelFormat is an array format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is an array, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -163,25 +426,84 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -#define SDL_ISPIXELFORMAT_ALPHA(format) \ - ((SDL_ISPIXELFORMAT_PACKED(format) && \ - ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))) - +/** + * A macro to determine if an SDL_PixelFormat is a 10-bit format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_10BIT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) +/** + * A macro to determine if an SDL_PixelFormat is a floating point format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ -#define SDL_ISPIXELFORMAT_FOURCC(format) \ +/** + * A macro to determine if an SDL_PixelFormat has an alpha channel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_ALPHA(format) \ + ((SDL_ISPIXELFORMAT_PACKED(format) && \ + ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ + (SDL_ISPIXELFORMAT_ARRAY(format) && \ + ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) + + +/** + * A macro to determine if an SDL_PixelFormat is a "FourCC" format. + * + * This covers custom and other unusual formats. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this enum, update SDL_GetPixelFormatName() */ @@ -221,7 +543,7 @@ typedef enum SDL_PackedLayout * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for * RGBA8888 on big-endian CPUs. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PixelFormat { @@ -351,59 +673,35 @@ typedef enum SDL_PixelFormat /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ - SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif } SDL_PixelFormat; -/* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 -#else -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888 -#endif - -/** - * Pixels are a representation of a color in a particular color space. - * - * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV. - * - * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen. - * https://en.wikipedia.org/wiki/RGB_color_model - * - * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component. - * https://en.wikipedia.org/wiki/YCbCr - * - * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from. - * - * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors. - * - * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space. - * https://en.wikipedia.org/wiki/CIE_1931_color_space - * - * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals. - * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics - * - * The matrix coefficients are used to convert between YCbCr and RGB colors. - */ - /** * Colorspace color type. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorType { @@ -416,7 +714,7 @@ typedef enum SDL_ColorType * Colorspace color range, as described by * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorRange { @@ -429,7 +727,7 @@ typedef enum SDL_ColorRange * Colorspace color primaries, as described by * https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorPrimaries { @@ -454,7 +752,7 @@ typedef enum SDL_ColorPrimaries * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TransferCharacteristics { @@ -484,7 +782,7 @@ typedef enum SDL_TransferCharacteristics * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MatrixCoefficients { @@ -508,7 +806,7 @@ typedef enum SDL_MatrixCoefficients /** * Colorspace chroma sample location. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ChromaLocation { @@ -520,22 +818,177 @@ typedef enum SDL_ChromaLocation /* Colorspace definition */ + +/** + * A macro for defining custom SDL_Colorspace formats. + * + * For example, defining SDL_COLORSPACE_SRGB looks like this: + * + * ```c + * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + * SDL_COLOR_RANGE_FULL, + * SDL_COLOR_PRIMARIES_BT709, + * SDL_TRANSFER_CHARACTERISTICS_SRGB, + * SDL_MATRIX_COEFFICIENTS_IDENTITY, + * SDL_CHROMA_LOCATION_NONE) + * ``` + * + * \param type the type of the new format, probably an SDL_ColorType value. + * \param range the range of the new format, probably a SDL_ColorRange value. + * \param primaries the primaries of the new format, probably an + * SDL_ColorPrimaries value. + * \param transfer the transfer characteristics of the new format, probably an + * SDL_TransferCharacteristics value. + * \param matrix the matrix coefficients of the new format, probably an + * SDL_MatrixCoefficients value. + * \param chroma the chroma sample location of the new format, probably an + * SDL_ChromaLocation value. + * \returns a format value in the style of SDL_Colorspace. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) -#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F) -#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F) -#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F) -#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) -#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) -#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F) +/** + * A macro to retrieve the type of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorType for `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) -#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) -#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) -#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) -#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) -#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) +/** + * A macro to retrieve the range of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorRange of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) + +/** + * A macro to retrieve the chroma sample location of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ChromaLocation of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) + +/** + * A macro to retrieve the primaries of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorPrimaries of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) + +/** + * A macro to retrieve the transfer characteristics of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_TransferCharacteristics of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) + +/** + * A macro to retrieve the matrix coefficients of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_MatrixCoefficients of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) + +/** + * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix + * coefficients. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT601 or BT470BG, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) + +/** + * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) + +/** + * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix + * coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT2020_NCL, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) + +/** + * A macro to determine if an SDL_Colorspace has a limited range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if limited range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) + +/** + * A macro to determine if an SDL_Colorspace has a full range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if full range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. @@ -544,7 +997,7 @@ typedef enum SDL_ChromaLocation * function, etc.), this is not an exhaustive list, but rather a * representative sample of the kinds of colorspaces supported in SDL. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_ColorPrimaries * \sa SDL_ColorRange @@ -631,7 +1084,7 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ - SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, SDL_COLOR_RANGE_FULL, SDL_COLOR_PRIMARIES_BT2020, @@ -639,15 +1092,10 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ } SDL_Colorspace; - -/* The default colorspace for RGB surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB - -/* The default colorspace for YUV surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG - /** * A structure that represents a color as RGBA components. * @@ -656,7 +1104,7 @@ typedef enum SDL_Colorspace * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Color { @@ -670,7 +1118,7 @@ typedef struct SDL_Color * The bits of this structure can be directly reinterpreted as a float-packed * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_FColor { @@ -683,7 +1131,7 @@ typedef struct SDL_FColor /** * A set of indexed colors representing a palette. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -698,7 +1146,7 @@ typedef struct SDL_Palette /** * Details about the format of a pixel. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PixelFormatDetails { @@ -729,7 +1177,7 @@ typedef struct SDL_PixelFormatDetails * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); @@ -742,16 +1190,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * \param Gmask a pointer filled in with the green mask for the format. * \param Bmask a pointer filled in with the blue mask for the format. * \param Amask a pointer filled in with the alpha mask for the format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatForMasks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); /** * Convert a bpp value and RGBA masks to an enumerated pixel format. @@ -769,7 +1217,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMasksForPixelFormat */ @@ -788,7 +1236,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); @@ -804,7 +1252,7 @@ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDet * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyPalette * \sa SDL_SetPaletteColors @@ -819,15 +1267,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); * \param colors an array of SDL_Color structures to copy into the palette. * \param firstcolor the index of the first palette entry to modify. * \param ncolors the number of entries to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); /** * Free a palette created with SDL_CreatePalette(). @@ -837,7 +1285,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette */ @@ -872,7 +1320,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB @@ -911,7 +1359,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -939,7 +1387,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -971,7 +1419,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform.h index bfdfa3a..e40f009 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,7 +51,7 @@ extern "C" { * \returns the name of the platform. If the correct platform name is not * available, returns a string beginning with the text "Unknown". * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform_defines.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform_defines.h index e7f91cf..7e9a0a9 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform_defines.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_platform_defines.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,180 +29,450 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 -#endif -#ifdef __NGAGE__ -#define SDL_PLATFORM_NGAGE 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ -#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif defined(HAVE_WINAPIFAMILY_H) && HAVE_WINAPIFAMILY_H + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT -#define SDL_PLATFORM_WINRT 1 +#error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_power.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_power.h index 1fdef78..4056ce3 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_power.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_power.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,15 @@ * # CategoryPower * * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ #include @@ -42,7 +51,7 @@ extern "C" { * * These are results returned by SDL_GetPowerInfo(). * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PowerState { @@ -80,7 +89,7 @@ typedef enum SDL_PowerState * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_process.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_process.h new file mode 100644 index 0000000..2cc7739 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_process.h @@ -0,0 +1,430 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used + * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set + * to `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value + * describing where standard error for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_properties.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_properties.h index c3a2c82..1f47d5f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_properties.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_properties.h @@ -1,6 +1,6 @@ /* - Simple DiretMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -61,14 +61,14 @@ extern "C" { /** * SDL properties ID * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PropertiesID; /** * SDL property type * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PropertyType { @@ -86,7 +86,7 @@ typedef enum SDL_PropertyType * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); @@ -100,7 +100,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyProperties */ @@ -116,14 +116,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); * * \param src the properties to copy. * \param dst the destination properties. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** * Lock a group of properties. @@ -138,16 +138,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SD * thread. * * \param props the properties to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockProperties */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** * Unlock a group of properties. @@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockProperties */ @@ -180,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); * \threadsafety This callback may fire without any locks held; if this is a * concern, the app should provide its own locking. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetPointerPropertyWithCleanup */ @@ -204,18 +204,18 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \param cleanup the function to call when this property is deleted, or NULL * if no cleanup is necessary. * \param userdata a pointer that is passed to the cleanup function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_SetPointerProperty * \sa SDL_CleanupPropertyCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); /** * Set a pointer property in a group of properties. @@ -223,12 +223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_HasProperty @@ -238,7 +238,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \sa SDL_SetPointerPropertyWithCleanup * \sa SDL_SetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); /** * Set a string property in a group of properties. @@ -249,16 +249,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID pro * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** * Set an integer property in a group of properties. @@ -266,16 +266,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumberProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** * Set a floating point property in a group of properties. @@ -283,16 +283,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetFloatProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** * Set a boolean property in a group of properties. @@ -300,31 +300,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); /** * Return whether a property exists in a group of properties. * * \param props the properties to query. * \param name the name of the property to query. - * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. + * \returns true if the property exists, or false if it doesn't. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** * Get the type of a property in a group of properties. @@ -336,7 +336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasProperty */ @@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty * \sa SDL_GetFloatProperty @@ -391,7 +391,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -413,7 +413,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -435,7 +435,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -457,27 +457,27 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty * \sa SDL_SetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); /** * Clear a property from a group of properties. * * \param props the properties to modify. * \param name the name of the property to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); /** * A callback used to enumerate all the properties in a group of properties. @@ -492,7 +492,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, c * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this * callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EnumerateProperties */ @@ -507,14 +507,14 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop * \param props the properties to query. * \param callback the function to call for each property. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** * Destroy a group of properties. @@ -528,7 +528,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID pr * locked or other threads might be setting or getting values * from these properties. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_rect.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_rect.h index ea97df9..8998de6 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_rect.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_rect.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,7 +23,7 @@ * # CategoryRect * * Some helper functions for managing rectangles and 2D points, in both - * interger and floating point versions. + * integer and floating point versions. */ #ifndef SDL_rect_h_ @@ -41,7 +41,7 @@ extern "C" { /** * The structure that defines a point (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect @@ -55,7 +55,7 @@ typedef struct SDL_Point /** * The structure that defines a point (using floating point values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat @@ -70,7 +70,7 @@ typedef struct SDL_FPoint /** * A rectangle, with the origin at the upper left (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmpty * \sa SDL_RectsEqual @@ -91,7 +91,7 @@ typedef struct SDL_Rect * A rectangle, with the origin at the upper left (using floating point * values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -121,7 +121,7 @@ typedef struct SDL_FRect * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) { @@ -146,16 +146,16 @@ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) { return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; } /** @@ -170,15 +170,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) { - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; } /** @@ -194,51 +194,51 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) { return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; + (a->w == b->w) && (a->h == b->h)) ? true : false; } /** * Determine whether two rectangles intersect. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); /** * Calculate the intersection of two rectangles. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate the union of two rectangles. @@ -247,12 +247,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate a minimal rectangle enclosing a set of points. @@ -266,12 +266,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const S * \param clip an SDL_Rect used for clipping or NULL to enclose all points. * \param result an SDL_Rect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); /** * Calculate the intersection of a rectangle and line segment. @@ -287,11 +287,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); /* SDL_FRect versions... */ @@ -311,16 +311,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Re * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) { return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && - (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; } /** @@ -335,15 +335,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) { - return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; } /** @@ -363,22 +363,22 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * \param a the first rectangle to test. * \param b the second rectangle to test. * \param epsilon the epsilon value for comparison. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualFloat */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) { return (a && b && ((a == b) || ((SDL_fabsf(a->x - b->x) <= epsilon) && (SDL_fabsf(a->y - b->y) <= epsilon) && (SDL_fabsf(a->w - b->w) <= epsilon) && (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; + ? true : false; } /** @@ -398,15 +398,15 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualEpsilon */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) { return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); } @@ -414,34 +414,34 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec /** * Determine whether two rectangles intersect with float precision. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); /** * Calculate the intersection of two rectangles with float precision. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersectionFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate the union of two rectangles with float precision. @@ -450,12 +450,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate a minimal rectangle enclosing a set of points with float @@ -470,12 +470,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, c * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); /** * Calculate the intersection of a rectangle and line segment with float @@ -492,11 +492,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_render.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_render.h index 706308c..891e994 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_render.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_render.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -40,8 +40,8 @@ * * This API is designed to accelerate simple 2D operations. You may want more * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. + * should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the + * many good 3D engines. * * These functions must be called from the main thread. See this bug for * details: https://github.com/libsdl-org/SDL/issues/986 @@ -51,10 +51,13 @@ #define SDL_render_h_ #include +#include #include #include +#include #include #include +#include #include #include @@ -66,14 +69,14 @@ extern "C" { /** * The name of the software renderer. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_SOFTWARE_RENDERER "software" /** * Vertex structure. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Vertex { @@ -85,7 +88,7 @@ typedef struct SDL_Vertex /** * The access pattern allowed for a texture. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TextureAccess { @@ -97,7 +100,7 @@ typedef enum SDL_TextureAccess /** * How the logical size is mapped to the output. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_RendererLogicalPresentation { @@ -111,15 +114,32 @@ typedef enum SDL_RendererLogicalPresentation /** * A structure representing rendering state * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Renderer SDL_Renderer; +#ifndef SDL_INTERNAL + /** * An efficient driver-specific representation of pixel data * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ @@ -135,7 +155,9 @@ typedef struct SDL_Texture SDL_Texture; * * \returns the number of built in render drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_GetRenderDriver @@ -158,7 +180,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * \returns the name of the rendering driver at the requested index, or NULL * if an invalid index was specified. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumRenderDrivers */ @@ -174,36 +198,43 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * SDL_CreateWindow()). * \param window a pointer filled with the window, or NULL on error. * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); /** * Create a 2D rendering context for a window. * * If you want a specific renderer, you can specify its name here. A list of - * available renderers can be obtained by calling SDL_GetRenderDriver multiple - * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't - * need a specific renderer, specify NULL and SDL will attempt to choose the - * best option for you, based on what is available on the user's system. + * available renderers can be obtained by calling SDL_GetRenderDriver() + * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you + * don't need a specific renderer, specify NULL and SDL will attempt to choose + * the best option for you, based on what is available on the user's system. + * + * If `name` is a comma-separated list, SDL will try each name, in the order + * listed, until one succeeds or all of them fail. * * By default the rendering size matches the window size in pixels, but you * can call SDL_SetRenderLogicalPresentation() to change the content size and * scaling options. * * \param window the window where rendering is displayed. - * \param name the name of the rendering driver to initialize, or NULL to - * initialize the first one supporting the requested flags. + * \param name the name of the rendering driver to initialize, or NULL to let + * SDL choose one. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRendererWithProperties * \sa SDL_CreateSoftwareRenderer @@ -225,7 +256,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * displayed, required if this isn't a software renderer using a surface * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering * is displayed, if you want a software renderer without a window - * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace + * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace * value describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and @@ -255,7 +286,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateRenderer @@ -290,7 +323,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRenderer */ @@ -303,7 +338,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surfac * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); @@ -314,7 +351,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); @@ -325,7 +364,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende * \returns the name of the selected renderer, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateRendererWithProperties @@ -348,21 +389,21 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN, * representing the available texture formats for this renderer. - * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with * HDR enabled. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is * automatically multiplied into the color scale. This property can change - * dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range * that can be displayed, in terms of the SDR white point. When HDR is not * enabled, this will be 1.0. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * * With the direct3d renderer: * @@ -403,11 +444,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * swapchain images, or potential frames in flight, used by the Vulkan * renderer * + * With the gpu renderer: + * + * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with + * the renderer + * * \param renderer the rendering context. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); @@ -434,6 +482,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende #define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count" +#define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device" /** * Get the output size in pixels of a rendering context. @@ -444,14 +493,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \param renderer the rendering context. * \param w a pointer filled in with the width in pixels. * \param h a pointer filled in with the height in pixels. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Get the current output size in pixels of a rendering context. @@ -464,28 +515,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *rende * \param renderer the rendering context. * \param w a pointer filled in with the current width. * \param h a pointer filled in with the current height. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Create a texture for a rendering context. * + * The contents of a texture when first created are not defined. + * * \param renderer the rendering context. * \param format one of the enumerated values in SDL_PixelFormat. * \param access one of the enumerated values in SDL_TextureAccess. * \param w the width of the texture in pixels. * \param h the height of the texture in pixels. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTextureFromSurface * \sa SDL_CreateTextureWithProperties @@ -513,7 +569,9 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureWithProperties @@ -526,7 +584,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * These are the supported properties: * - * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for @@ -617,11 +675,12 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * \param renderer the rendering context. * \param props the properties to use. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateTexture @@ -661,7 +720,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * The following read-only properties are provided by SDL: * - * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing + * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing * the texture colorspace. * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in * SDL_PixelFormat. @@ -701,14 +760,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * With the vulkan renderer: * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_POINTER`: the VkImage associated with - * the texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_U_POINTER`: the VkImage associated with - * the U plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_V_POINTER`: the VkImage associated with - * the V plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_UV_POINTER`: the VkImage associated with - * the UV plane of a NV12/NV21 texture + * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the + * texture * * With the opengl renderer: * @@ -740,16 +793,13 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc) * - * With the vulkan renderer: - * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the - * texture - * * \param texture the texture to query. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); @@ -789,7 +839,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Textur * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture); @@ -801,12 +851,14 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This * argument can be NULL if you don't need this information. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); /** * Set an additional color value multiplied into render copy operations. @@ -818,22 +870,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, fl * `srcC = srcC * (color / 255)` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); /** @@ -846,22 +900,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture * `srcC = srcC * color` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); /** @@ -871,16 +927,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *te * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); /** * Get the additional color value multiplied into render copy operations. @@ -889,16 +947,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); /** * Set an additional alpha value multiplied into render copy operations. @@ -909,20 +969,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *te * `srcA = srcA * (alpha / 255)` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); /** * Set an additional alpha value multiplied into render copy operations. @@ -933,83 +995,93 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture * `srcA = srcA * alpha` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); /** * Set the blend mode for a texture, used by SDL_RenderTexture(). * * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. + * and this function returns false. * * \param texture the texture to update. * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); /** * Get the blend mode used for texture copy operations. * * \param texture the texture to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); /** * Set the scale mode used for texture scale operations. @@ -1020,28 +1092,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *textur * * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); /** * Get the scale mode used for texture scale operations. * * \param texture the texture to query. * \param scaleMode a pointer filled in with the current scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); /** * Update the given texture rectangle with new pixel data. @@ -1063,17 +1139,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *textur * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding * between lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture * \sa SDL_UpdateNVTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); /** * Update a rectangle within a planar YV12 or IYUV texture with new pixel @@ -1095,15 +1173,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, con * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateNVTexture * \sa SDL_UpdateTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, @@ -1125,15 +1205,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \param UVplane the raw pixel data for the UV plane. * \param UVpitch the number of bytes between rows of pixel data for the UV * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch); @@ -1157,16 +1239,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the * pitch is the length of one row in bytes. - * \returns SDL_TRUE on success or SDL_FALSE if the texture is not valid or - * was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. + * \returns true on success or false if the texture is not valid or was not + * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTextureToSurface * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch); @@ -1192,17 +1276,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** * Unlock a texture, uploading the changes to video memory, if needed. @@ -1217,7 +1303,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *textu * * \param texture a texture locked by SDL_LockTexture(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture */ @@ -1234,14 +1322,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderTarget */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** * Get the current render target. @@ -1252,7 +1342,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderTarget */ @@ -1261,13 +1353,23 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend /** * Set a device independent resolution and presentation mode for rendering. * - * This function sets the width and height of the logical rendering output. A - * render target is created at the specified size and used for rendering and - * then copied to the output during presentation. + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the window is always the requested dimensions, + * scaling to the actual window resolution as necessary. + * + * This can be useful for games that expect a fixed size, but would like to + * scale the output to whatever is available, regardless of how a user resizes + * a window, or if the display is high DPI. * * You can disable logical coordinates by setting the mode to * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel - * resolution of the output window. + * resolution of the output window; it is safe to toggle logical presentation + * during the rendering of a frame: perhaps most of the rendering is done to + * specific dimensions but to make fonts look sharp, the app turns off logical + * presentation while drawing text. + * + * Letterboxing will only happen if logical presentation is enabled during + * SDL_RenderPresent; be sure to reenable it first if you were using it. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). @@ -1276,17 +1378,18 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \param w the width of the logical resolution. * \param h the height of the logical resolution. * \param mode the presentation mode used. - * \param scale_mode the scale mode used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertEventToRenderCoordinates * \sa SDL_GetRenderLogicalPresentation * \sa SDL_GetRenderLogicalPresentationRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); /** * Get device independent resolution and presentation mode for rendering. @@ -1297,16 +1400,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param w an int to be filled with the width. * \param h an int to be filled with the height. - * \param mode a pointer filled in with the presentation mode. - * \param scale_mode a pointer filled in with the scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); /** * Get the final presentation rectangle for rendering. @@ -1319,36 +1423,54 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param rect a pointer filled in with the final presentation rectangle, may * be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); /** * Get a point in render coordinates when given a point in window coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param window_x the x coordinate in window coordinates. * \param window_y the y coordinate in window coordinates. * \param x a pointer filled with the x coordinate in render coordinates. * \param y a pointer filled with the y coordinate in render coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); /** * Get a point in window coordinates when given a point in render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param x the x coordinate in render coordinates. * \param y the y coordinate in render coordinates. @@ -1356,65 +1478,95 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Rendere * coordinates. * \param window_y a pointer filled with the y coordinate in window * coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); /** * Convert the coordinates in an event to render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * Various event types are converted with this function: mouse, touch, pen, + * etc. + * * Touch coordinates are converted from normalized coordinates in the window * to non-normalized rendering coordinates. * - * Once converted, the coordinates may be outside the rendering area. + * Relative mouse coordinates (xrel and yrel event fields) are _also_ + * converted. Applications that do not want these fields converted should use + * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of + * converting the entire event structure. + * + * Once converted, coordinates may be outside the rendering area. * * \param renderer the rendering context. * \param event the event to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderCoordinatesFromWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); /** * Set the drawing area for rendering on the current target. * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL * to set the viewport to the entire target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_RenderViewportSet */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the drawing area for the current target. * * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current drawing area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderViewportSet * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); /** * Return whether an explicit rectangle was set as the viewport. @@ -1424,15 +1576,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *rendere * viewport is always reset when changing rendering targets. * * \param renderer the rendering context. - * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target). + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); /** * Get the safe area for rendering within the current viewport. @@ -1447,12 +1601,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect a pointer filled in with the area that is safe for interactive * content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); /** * Set the clip rectangle for rendering on the specified target. @@ -1460,15 +1616,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the clip area, relative to * the viewport, or NULL to disable clipping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_RenderClipEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the clip rectangle for the current target. @@ -1476,29 +1634,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current clipping area * or an empty rectangle if clipping is disabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderClipEnabled * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); /** * Get whether clipping is enabled on the given renderer. * * \param renderer the rendering context. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. + * \returns true if clipping is enabled or false if not; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); /** * Set the drawing scale for rendering on the current target. @@ -1514,14 +1676,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * \param renderer the rendering context. * \param scaleX the horizontal scaling factor. * \param scaleY the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); /** * Get the drawing scale for the current target. @@ -1529,14 +1693,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, * \param renderer the rendering context. * \param scaleX a pointer filled in with the horizontal scaling factor. * \param scaleY a pointer filled in with the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); /** * Set the color used for drawing operations. @@ -1551,15 +1717,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to * specify how the alpha channel is used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColor * \sa SDL_SetRenderDrawColorFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Set the color used for drawing operations (Rect, Line and Clear). @@ -1574,15 +1742,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *render * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is * used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1596,15 +1766,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *r * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1618,15 +1790,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *render * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColorFloat * \sa SDL_GetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); /** * Set the color scale used for render operations. @@ -1641,28 +1815,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *r * * \param renderer the rendering context. * \param scale the color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); /** * Get the color scale used for render operations. * * \param renderer the rendering context. * \param scale a pointer filled in with the current color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); /** * Set the blend mode used for drawing operations (Fill and Line). @@ -1671,28 +1849,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *rende * * \param renderer the rendering context. * \param blendMode the SDL_BlendMode to use for blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); /** * Get the blend mode used for drawing operations. * * \param renderer the rendering context. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); /** * Clear the current rendering target with the drawing color. @@ -1703,14 +1885,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *re * SDL_SetRenderDrawColor() when needed. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. @@ -1718,14 +1902,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \param renderer the renderer which should draw a point. * \param x the x coordinate of the point. * \param y the y coordinate of the point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); /** * Draw multiple points on the current rendering target at subpixel precision. @@ -1733,14 +1919,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, flo * \param renderer the renderer which should draw multiple points. * \param points the points to draw. * \param count the number of points to draw. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a line on the current rendering target at subpixel precision. @@ -1750,14 +1938,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, co * \param y1 the y coordinate of the start point. * \param x2 the x coordinate of the end point. * \param y2 the y coordinate of the end point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLines */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); /** * Draw a series of connected lines on the current rendering target at @@ -1766,14 +1956,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, floa * \param renderer the renderer which should draw multiple lines. * \param points the points along the lines. * \param count the number of points, drawing count-1 lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLine */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a rectangle on the current rendering target at subpixel precision. @@ -1781,14 +1973,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, con * \param renderer the renderer which should draw a rectangle. * \param rect a pointer to the destination rectangle, or NULL to outline the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Draw some number of rectangles on the current rendering target at subpixel @@ -1797,14 +1991,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, cons * \param renderer the renderer which should draw multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Fill a rectangle on the current rendering target with the drawing color at @@ -1813,14 +2009,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, con * \param renderer the renderer which should fill a rectangle. * \param rect a pointer to the destination rectangle, or NULL for the entire * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Fill some number of rectangles on the current rendering target with the @@ -1829,14 +2027,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, * \param renderer the renderer which should fill multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Copy a portion of the texture to the current rendering target at subpixel @@ -1848,15 +2048,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, * texture. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTextureRotated * \sa SDL_RenderTextureTiled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); /** * Copy a portion of the source texture to the current rendering target, with @@ -1875,17 +2077,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, S * around dstrect.w/2, dstrect.h/2). * \param flip an SDL_FlipMode value stating which flipping actions should be * performed on the texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, - const double angle, const SDL_FPoint *center, - const SDL_FlipMode flip); + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); + +/** + * Copy a portion of the source texture to the current rendering target, with + * affine transform, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param origin a pointer to a point indicating where the top-left corner of + * srcrect should be mapped to, or NULL for the rendering + * target's origin. + * \param right a pointer to a point indicating where the top-right corner of + * srcrect should be mapped to, or NULL for the rendering + * target's top-right corner. + * \param down a pointer to a point indicating where the bottom-left corner of + * srcrect should be mapped to, or NULL for the rendering target's + * bottom-left corner. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FPoint *origin, + const SDL_FPoint *right, const SDL_FPoint *down); /** * Tile a portion of the texture to the current rendering target at subpixel @@ -1903,14 +2137,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *rend * 64x64 tiles. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); /** * Perform a scaled copy using the 9-grid algorithm to the current rendering @@ -1935,14 +2171,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *render * corner of `dstrect`, or 0.0f for an unscaled copy. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); /** * Render a list of triangles, optionally using a texture and indices into the @@ -1957,14 +2195,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *render * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices number of indices. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometryRaw */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices); @@ -1987,14 +2227,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * if NULL all vertices will be rendered in sequential order. * \param num_indices number of indices. * \param size_indices index size: 1 (byte), 2 (short), 4 (int). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometry */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, @@ -2017,7 +2259,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *rendere * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); @@ -2041,18 +2285,20 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * pixel. * * Please note, that in case of rendering to a texture - there is **no need** - * to call `SDL_RenderPresent` after drawing needed objects to a texture, you - * are only required to change back the rendering target to default via - * `SDL_SetRenderTarget(renderer, NULL)` afterwards, as textures by themselves - * do not have a concept of backbuffers. + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \threadsafety You may only call this function on the main thread. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_RenderClear @@ -2067,7 +2313,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \sa SDL_SetRenderDrawBlendMode * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); /** * Destroy the specified texture. @@ -2077,7 +2323,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureFromSurface @@ -2092,7 +2340,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer */ @@ -2122,12 +2372,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * be prepared to make changes if specific state needs to be protected. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); /** * Get the CAMetalLayer associated with the given Metal renderer. @@ -2139,7 +2391,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalCommandEncoder */ @@ -2160,7 +2414,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalLayer */ @@ -2187,15 +2443,15 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not * needed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is **NOT** safe to call this function from two threads at * once. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); /** * Toggle VSync of the given renderer. @@ -2204,21 +2460,23 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer * * The `vsync` parameter can be 1 to synchronize present with every vertical * refresh, 2 to synchronize present with every second vertical refresh, etc., - * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), - * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is - * supported by every driver, so you should check the return value to see - * whether the requested setting is supported. + * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or + * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by + * every driver, so you should check the return value to see whether the + * requested setting is supported. * * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); #define SDL_RENDERER_VSYNC_DISABLED 0 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1) @@ -2229,14 +2487,96 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, * \param renderer the renderer to toggle. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetRenderVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); + +/** + * The size, in pixels, of a single SDL_RenderDebugText() character. + * + * The font is monospaced and square, so this applies to all characters. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + */ +#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8 + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a string of text to an SDL_Renderer. Note that + * this is a convenience function for debugging, with severe limitations, and + * not intended to be used for production apps and games. + * + * Among these limitations: + * + * - It accepts UTF-8 strings, but will only renders ASCII characters. + * - It has a single, tiny size (8x8 pixels). One can use logical presentation + * or scaling to adjust it, but it will be blurry. + * - It uses a simple, hardcoded bitmap font. It does not allow different font + * selections and it does not support truetype, for proper scaling. + * - It does no word-wrapping and does not treat newline characters as a line + * break. If the text goes out of the window, it's gone. + * + * For serious text rendering, there are several good options, such as + * SDL_ttf, stb_truetype, or other external libraries. + * + * On first use, this will create an internal texture for rendering glyphs. + * This texture will live until the renderer is destroyed. + * + * The text is drawn in the color specified by SDL_SetRenderDrawColor(). + * + * \param renderer the renderer which should draw a line of text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param str the string to render. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugTextFormat + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str); + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a printf()-style format string to a renderer. + * Note that this is a convinence function for debugging, with severe + * limitations, and is not intended to be used for production apps and games. + * + * For the full list of limitations and other useful information, see + * SDL_RenderDebugText. + * + * \param renderer the renderer which should draw the text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param fmt the format string to draw. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_revision.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_revision.h index f78e5d9..18f7c4d 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_revision.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_revision.h @@ -1,22 +1,22 @@ /* - Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga - 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. + 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: + 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. + 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. */ /* WIKI CATEGORY: Version */ @@ -48,9 +48,9 @@ */ #define SDL_REVISION "Some arbitrary string decided at SDL build time" #elif defined(SDL_VENDOR_INFO) -#define SDL_REVISION SDL_VENDOR_INFO +#define SDL_REVISION "release-3.2.0-0-g535d80bad (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "" +#define SDL_REVISION "release-3.2.0-0-g535d80bad" #endif #endif /* SDL_revision_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_scancode.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_scancode.h index ccf8bb5..9650a6c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_scancode.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_scancode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryScancode * * Defines keyboard scancodes. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_scancode_h_ @@ -42,7 +47,7 @@ * The values in this enumeration are based on the USB usage page standard: * https://usb.org/sites/default/files/hut1_5.pdf * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_Scancode { @@ -417,8 +422,8 @@ typedef enum SDL_Scancode SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_sensor.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_sensor.h index 3ae4856..b220f05 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_sensor.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_sensor.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategorySensor * * SDL sensor management. + * + * These APIs grant access to gyros and accelerometers on various platforms. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ @@ -41,14 +47,10 @@ extern "C" { #endif /** - * SDL_sensor.h + * The opaque structure used to identify an opened SDL sensor. * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system - * for sensors, and load appropriate drivers. + * \since This struct is available since SDL 3.2.0. */ - -struct SDL_Sensor; typedef struct SDL_Sensor SDL_Sensor; /** @@ -57,7 +59,7 @@ typedef struct SDL_Sensor SDL_Sensor; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SensorID; @@ -69,7 +71,7 @@ typedef Uint32 SDL_SensorID; * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the * earth, which is a positive Y value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_STANDARD_GRAVITY 9.80665f @@ -123,7 +125,7 @@ typedef Uint32 SDL_SensorID; * * The gyroscope axis data is not changed when the device is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayOrientation */ @@ -151,7 +153,7 @@ typedef enum SDL_SensorType * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); @@ -163,7 +165,7 @@ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); * \param instance_id the sensor instance ID. * \returns the sensor name, or NULL if `instance_id` is not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id); @@ -176,7 +178,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID ins * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is * not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID instance_id); @@ -189,7 +191,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID i * \returns the sensor platform dependent type, or -1 if `instance_id` is not * valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); @@ -200,7 +202,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id); @@ -211,7 +213,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); @@ -222,7 +224,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instan * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); @@ -233,7 +235,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor * \returns the sensor name or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); @@ -244,7 +246,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor); @@ -254,7 +256,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor) * \param sensor the SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor); @@ -265,7 +267,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor) * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); @@ -277,19 +279,19 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); * \param sensor the SDL_Sensor object to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** * Close a sensor previously opened with SDL_OpenSensor(). * * \param sensor the SDL_Sensor object to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); @@ -302,7 +304,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); * This needs to be called from the thread that initialized the sensor * subsystem. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateSensors(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_stdinc.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_stdinc.h index 5539f2a..4e15a3c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_stdinc.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_stdinc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,25 @@ /** * # CategoryStdinc * - * This is a general header that includes C language support. It implements a - * subset of the C runtime: these should all behave the same way as their C - * runtime equivalents, but with an SDL_ prefix. + * SDL provides its own implementation of some of the most important C runtime + * functions. + * + * Using these functions allows an app to have access to common C + * functionality without depending on a specific C runtime (or a C runtime at + * all). More importantly, the SDL implementations work identically across + * platforms, so apps can avoid surprises like snprintf() behaving differently + * between Windows and Linux builds, or itoa() only existing on some + * platforms. + * + * For many of the most common functions, like SDL_memcpy, SDL might just call + * through to the usual C runtime behind the scenes, if it makes sense to do + * so (if it's faster and always available/reliable on a given platform), + * reducing library size and offering the most optimized option. + * + * SDL also offers other C-runtime-adjacent functionality in this header that + * either isn't, strictly speaking, part of any C runtime standards, like + * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better + * options, like SDL_strlcpy(), which functions as a safer form of strcpy(). */ #ifndef SDL_stdinc_h_ @@ -32,17 +48,34 @@ #include -#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -#include -#endif #include -#ifndef __cplusplus -#include -#endif #include #include #include +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H) +#if __has_include() +#define SDL_INCLUDE_STDBOOL_H +#endif +#endif +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + #ifndef SDL_DISABLE_ALLOCA # ifndef alloca # ifdef HAVE_ALLOCA_H @@ -74,31 +107,120 @@ void *alloca(size_t); # endif #endif -#ifdef SIZE_MAX + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Don't let SDL use "long long" C types. + * + * SDL will define this if it believes the compiler doesn't understand the + * "long long" syntax for C datatypes. This can happen on older compilers. + * + * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it + * is safe to define this yourself to build against the SDL headers. + * + * If this is defined, it will remove access to some C runtime support + * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype + * explicitly. The rest of SDL will still be available. + * + * SDL's own source code cannot be built with a compiler that has this + * defined, for various technical reasons. + */ +#define SDL_NOLONGLONG 1 + +#elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */ +# define SDL_NOLONGLONG 1 +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The largest value that a `size_t` can hold for the target platform. + * + * `size_t` is generally the same size as a pointer in modern times, but this + * can get weird on very old and very esoteric machines. For example, on a + * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment + * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with + * the offset into an individual segment. + * + * In modern times, it's generally expected to cover an entire linear address + * space. But be careful! + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SIZE_MAX SIZE_MAX + +#elif defined(SIZE_MAX) # define SDL_SIZE_MAX SIZE_MAX #else # define SDL_SIZE_MAX ((size_t) -1) #endif +#ifndef SDL_COMPILE_TIME_ASSERT +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + /** - * Check if the compiler supports a given builtin. - * Supported by virtually all clang versions and recent gcc. Use this - * instead of checking the clang version if possible. + * A compile-time assertion. + * + * This can check constant values _known to the compiler at build time_ for + * correctness, and end the compile with the error if they fail. + * + * Often times these are used to verify basic truths, like the size of a + * datatype is what is expected: + * + * ```c + * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); + * ``` + * + * The `name` parameter must be a valid C symbol, and must be unique across + * all compile-time asserts in the same compilation unit (one run of the + * compiler), or the build might fail with cryptic errors on some targets. + * This is used with a C language trick that works on older compilers that + * don't support better assertion techniques. + * + * If you need an assertion that operates at runtime, on variable data, you + * should try SDL_assert instead. + * + * \param name a unique identifier for this assertion. + * \param x the value to test. Must be a boolean value. + * + * \threadsafety This macro doesn't generate any code to run. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_assert */ -#ifdef __has_builtin -#define SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define SDL_HAS_BUILTIN(x) 0 +#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x) +#elif defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] #endif /** - * The number of elements in an array. + * The number of elements in a static array. + * + * This will compile but return incorrect results for a pointer to an array; + * it has to be an array the compiler knows the size of. * * This macro looks like it double-evaluates the argument, but it does so * inside of `sizeof`, so there are no side-effects here, as expressions do * not actually run any code in these cases. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) @@ -111,7 +233,9 @@ void *alloca(size_t); * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * ``` * - * \since This macro is available since SDL 3.0.0. + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -122,7 +246,76 @@ void *alloca(size_t); * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). */ /* @{ */ -#ifdef __cplusplus + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) #define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) #define SDL_static_cast(type, expression) static_cast(expression) #define SDL_const_cast(type, expression) const_cast(expression) @@ -131,9 +324,23 @@ void *alloca(size_t); #define SDL_static_cast(type, expression) ((type)(expression)) #define SDL_const_cast(type, expression) ((type)(expression)) #endif + /* @} *//* Cast operators */ -/* Define a four character code as a Uint32 */ +/** + * Define a four character code as a Uint32. + * + * \param A the first ASCII character. + * \param B the second ASCII character. + * \param C the third ASCII character. + * \param D the fourth ASCII character. + * \returns the four characters converted into a Uint32, one character + * per-byte. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FOURCC(A, B, C, D) \ ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ @@ -149,7 +356,7 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -162,63 +369,49 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ -#elif defined(INT64_C) +#else /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +#ifndef SDL_SINT64_C +#if defined(INT64_C) #define SDL_SINT64_C(c) INT64_C(c) -#define SDL_UINT64_C(c) UINT64_C(c) #elif defined(_MSC_VER) #define SDL_SINT64_C(c) c ## i64 -#define SDL_UINT64_C(c) c ## ui64 #elif defined(__LP64__) || defined(_LP64) #define SDL_SINT64_C(c) c ## L -#define SDL_UINT64_C(c) c ## UL #else #define SDL_SINT64_C(c) c ## LL +#endif +#endif /* !SDL_SINT64_C */ + +#ifndef SDL_UINT64_C +#if defined(UINT64_C) +#define SDL_UINT64_C(c) UINT64_C(c) +#elif defined(_MSC_VER) +#define SDL_UINT64_C(c) c ## ui64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_UINT64_C(c) c ## UL +#else #define SDL_UINT64_C(c) c ## ULL #endif +#endif /* !SDL_UINT64_C */ + +#endif /* !SDL_WIKI_DOCUMENTATION_SECTION */ /** * \name Basic data types */ /* @{ */ -/** - * A boolean false. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_FALSE false - -/** - * A boolean true. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_TRUE true - -/** - * A boolean type: true or false. - * - * \since This datatype is available since SDL 3.0.0. - * - * \sa SDL_TRUE - * \sa SDL_FALSE - */ -typedef bool SDL_bool; - /** * A signed 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ @@ -227,7 +420,7 @@ typedef int8_t Sint8; /** * An unsigned 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ @@ -236,7 +429,7 @@ typedef uint8_t Uint8; /** * A signed 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ @@ -245,7 +438,7 @@ typedef int16_t Sint16; /** * An unsigned 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ @@ -254,7 +447,7 @@ typedef uint16_t Uint16; /** * A signed 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ @@ -263,7 +456,7 @@ typedef int32_t Sint32; /** * An unsigned 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ @@ -272,7 +465,7 @@ typedef uint32_t Uint32; /** * A signed 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ @@ -283,7 +476,7 @@ typedef int64_t Sint64; /** * An unsigned 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -299,7 +492,7 @@ typedef uint64_t Uint64; * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with * SDL_TimeToWindows() and SDL_TimeFromWindows(). * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_MAX_SINT64 * \sa SDL_MIN_SINT64 @@ -325,40 +518,217 @@ typedef Sint64 SDL_Time; * Equals by default to platform-defined `FLT_EPSILON`, or * `1.1920928955078125e-07F` if that's not available. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ #endif /* @} *//* Floating-point constants */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A printf-formatting string for an Sint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs64 "lld" + +/** + * A printf-formatting string for a Uint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu64 "llu" + +/** + * A printf-formatting string for a Uint64 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx64 "llx" + +/** + * A printf-formatting string for a Uint64 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX64 "llX" + +/** + * A printf-formatting string for an Sint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs32 "d" + +/** + * A printf-formatting string for a Uint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu32 "u" + +/** + * A printf-formatting string for a Uint32 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx32 "x" + +/** + * A printf-formatting string for a Uint32 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX32 "X" + +/** + * A printf-formatting string prefix for a `long long` value. + * + * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu, + * SDL_PRILLx, or SDL_PRILLX instead. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILL_PREFIX "ll" + +/** + * A printf-formatting string for a `long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLd SDL_PRILL_PREFIX "d" + +/** + * A printf-formatting string for a `unsigned long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLu SDL_PRILL_PREFIX "u" + +/** + * A printf-formatting string for an `unsigned long long` value as lower-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLx SDL_PRILL_PREFIX "x" + +/** + * A printf-formatting string for an `unsigned long long` value as upper-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* SDL_WIKI_DOCUMENTATION_SECTION */ + /* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. + * should define these but this is not true all platforms. * (for example win32) */ #ifndef SDL_PRIs64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIs64 "I64d" -#elif defined(PRIs64) -#define SDL_PRIs64 PRIs64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(PRId64) +#define SDL_PRIs64 PRId64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIs64 "ld" #else #define SDL_PRIs64 "lld" #endif #endif #ifndef SDL_PRIu64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIu64 "I64u" #elif defined(PRIu64) #define SDL_PRIu64 PRIu64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIu64 "lu" #else #define SDL_PRIu64 "llu" #endif #endif #ifndef SDL_PRIx64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIx64 "I64x" #elif defined(PRIx64) #define SDL_PRIx64 PRIx64 @@ -369,7 +739,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIX64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIX64 "I64X" #elif defined(PRIX64) #define SDL_PRIX64 PRIX64 @@ -407,9 +777,318 @@ typedef Sint64 SDL_Time; #define SDL_PRIX32 "X" #endif #endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#endif +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Macro that annotates function params with input buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + * ``` + * + * This notes that `src` should be `len` bytes in size and is only read by the + * function. The compiler or other analysis tools can warn when this doesn't + * appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) + +/** + * Macro that annotates function params with input/output string buffer size. + * + * If we were to annotate `strlcat`: + * + * ```c + * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + * ``` + * + * This notes that `dst` is a null-terminated C string, should be `maxlen` + * bytes in size, and is both read from and written to by the function. The + * compiler or other analysis tools can warn when this doesn't appear to be + * the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) + +/** + * Macro that annotates function params with output string buffer size. + * + * If we were to annotate `snprintf`: + * + * ```c + * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...); + * ``` + * + * This notes that `text` is a null-terminated C string, should be `maxlen` + * bytes in size, and is only written to by the function. The compiler or + * other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `wcsncpy`: + * + * ```c + * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` wchar_t in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for + * bytes. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_CAP(x) _Out_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) + +/** + * Macro that annotates function params with output buffer string size. + * + * If we were to annotate `strcpy`: + * + * ```c + * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and a zero-terminated string is written to it by the function. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +/** + * Macro that annotates function params as printf-style format strings. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a printf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ + +/** + * Macro that annotates function params as scanf-style format strings. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a scanf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ + +/** + * Macro that annotates a vararg function that operates like printf. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like printf. + * + * If we were to annotate `vfprintf`: + * + * ```c + * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like scanf. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by `...`. The compiler or other analysis tools can warn when this + * doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like scanf. + * + * If we were to annotate `vfscanf`: + * + * ```c + * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by a va_list. The compiler or other analysis tools can warn when + * this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like wprintf. + * + * If we were to annotate `fwprintf`: + * + * ```c + * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ + +/** + * Macro that annotates a va_list function that operates like wprintf. + * + * If we were to annotate `vfwprintf`: + * + * ```c + * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + +#elif defined(SDL_DISABLE_ANALYZE_MACROS) #define SDL_IN_BYTECAP(x) #define SDL_INOUT_Z_CAP(x) #define SDL_OUT_Z_CAP(x) @@ -423,7 +1102,7 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -447,53 +1126,45 @@ typedef Sint64 SDL_Time; #define SDL_PRINTF_FORMAT_STRING #define SDL_SCANF_FORMAT_STRING #endif -#ifdef __GNUC__ +#if defined(__GNUC__) || defined(__clang__) #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(bool, sizeof(SDL_bool) == 1); -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +#endif +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ /** \endcond */ @@ -523,7 +1194,96 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); extern "C" { #endif -#ifndef SDL_DISABLE_ALLOCA +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Allocate memory on the stack (maybe). + * + * If SDL knows how to access alloca() on the current platform, it will use it + * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to + * heap-allocate memory. + * + * Since this might not be stack memory at all, it's important that you check + * the returned pointer for NULL, and that you call SDL_stack_free on the + * memory when done with it. Since this might be stack memory, it's important + * that you don't allocate large amounts of it, or allocate in a loop without + * returning from the function, so the stack doesn't overflow. + * + * \param type the datatype of the memory to allocate. + * \param count the number of `type` objects to allocate. + * \returns newly-allocated memory, or NULL on failure. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_free + */ +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ +#define SDL_stack_free(data) +#elif !defined(SDL_DISABLE_ALLOCA) #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) #define SDL_stack_free(data) #else @@ -531,14 +1291,184 @@ extern "C" { #define SDL_stack_free(data) SDL_free(data) #endif +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If you want to allocate memory aligned to a specific alignment, consider + * using SDL_aligned_alloc(). + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void (SDLCALL *SDL_free_func)(void *mem); /** @@ -556,7 +1486,7 @@ typedef void (SDLCALL *SDL_free_func)(void *mem); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, @@ -575,7 +1505,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func * unlikely event of a background thread calling * SDL_SetMemoryFunctions simultaneously. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions @@ -599,42 +1529,42 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \param calloc_func custom calloc function. * \param realloc_func custom realloc function. * \param free_func custom free function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but one * should not replace the memory functions once any allocations * are made! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_calloc_func calloc_func, SDL_realloc_func realloc_func, SDL_free_func free_func); /** - * Allocate memory aligned to a specific value. - * - * If `alignment` is less than the size of `void *`, then it will be increased - * to match that. - * - * The returned memory address will be a multiple of the alignment value, and - * the amount of memory allocated will be a multiple of the alignment value. + * Allocate memory aligned to a specific alignment. * * The memory returned by this function must be freed with SDL_aligned_free(), - * and _not_ SDL_free. + * _not_ SDL_free(). * - * \param alignment the alignment requested. + * If `alignment` is less than the size of `void *`, it will be increased to + * match that. + * + * The returned memory address will be a multiple of the alignment value, and + * the size of the memory allocated will be a multiple of the alignment value. + * + * \param alignment the alignment of the memory. * \param size the size to allocate. - * \returns a pointer to the aligned memory. + * \returns a pointer to the aligned memory, or NULL if allocation failed. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_free */ @@ -646,11 +1576,13 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment * The pointer is no longer valid after this call and cannot be dereferenced * anymore. * - * \param mem a pointer previously returned by SDL_aligned_alloc. + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc */ @@ -659,31 +1591,552 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); /** * Get the number of outstanding (unfreed) allocations. * - * \returns the number of allocations. + * \returns the number of allocations or -1 if allocation counting is + * disabled. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); -extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); -extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); +/** + * Compute the absolute value of `x`. + * + * \param x an integer value. + * \returns the absolute value of x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); -/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ +/** + * Return the lesser of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) + +/** + * Return the greater of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `>` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) + +/** + * Return a value clamped to a range. + * + * If `x` is outside the range a values between `a` and `b`, the returned + * value will be `a` or `b` as appropriate. Otherwise, `x` is returned. + * + * This macro will produce incorrect results if `b` is less than `a`. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` and `>` operators. However, it double-evaluates all its parameters, so + * do not use expressions with side-effects here. + * + * \param x the value to compare. + * \param a the low end value. + * \param b the high end value. + * \returns x, clamped between a and b. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) /** @@ -697,7 +2150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); @@ -712,7 +2165,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); @@ -727,7 +2180,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); @@ -742,7 +2195,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); @@ -757,7 +2210,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); @@ -772,7 +2225,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); @@ -787,7 +2240,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isgraph * \sa SDL_isalnum @@ -812,7 +2265,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); @@ -827,7 +2280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); @@ -842,7 +2295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); @@ -861,7 +2314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); @@ -880,7 +2333,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isprint */ @@ -900,7 +2353,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); @@ -918,13 +2371,96 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); +/** + * Calculate a CRC-16 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-16 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-16 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); + +/** + * Calculate a CRC-32 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-32 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-32 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); +/** + * Calculate a 32-bit MurmurHash3 value for a block of data. + * + * https://en.wikipedia.org/wiki/MurmurHash + * + * A seed may be specified, which changes the final results consistently, but + * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous + * result from this function back into itself as the next seed value to + * calculate a hash in chunks; it won't produce the same hash as it would if + * the same data was provided in a single call. + * + * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not + * cryptographically secure, so it shouldn't be used for hashing top-secret + * data. + * + * \param data the data to be hashed. + * \param len the size of data, in bytes. + * \param seed a value that alters the final hash value. + * \returns a Murmur3 32-bit hash value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); + +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memmove + */ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memcpy */ @@ -935,10 +2471,52 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD #define SDL_memcpy memcpy #endif + +/** + * A macro to copy memory between objects, with basic type checking. + * + * SDL_memcpy and SDL_memmove do not care where you copy memory to and from, + * which can lead to bugs. This macro aims to avoid most of those bugs by + * making sure that the source and destination are both pointers to objects + * that are the same size. It does not check that the objects are the same + * _type_, just that the copy will not overflow either object. + * + * The size check happens at compile time, and the compiler will throw an + * error if the objects are different sizes. + * + * Generally this is intended to copy a single object, not an array. + * + * This macro looks like it double-evaluates its parameters, but the extras + * them are in `sizeof` sections, which generate no code nor side-effects. + * + * \param dst a pointer to the destination object. Must not be NULL. + * \param src a pointer to the source object. Must not be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ #define SDL_copyp(dst, src) \ { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) +/** + * Copy memory ranges that might overlap. + * + * It is okay for the memory regions to overlap. If you are confident that the + * regions never overlap, using SDL_memcpy() may improve performance. + * + * \param dst The destination memory region. Must not be NULL. + * \param src The source memory region. Must not be NULL. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memcpy + */ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memmove */ @@ -949,7 +2527,44 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, S #define SDL_memmove memmove #endif +/** + * Initialize all bytes of buffer of memory to a specific value. + * + * This function will set `len` bytes, pointed to by `dst`, to the value + * specified in `c`. + * + * Despite `c` being an `int` instead of a `char`, this only operates on + * bytes; `c` must be a value between 0 and 255, inclusive. + * + * \param dst the destination memory region. Must not be NULL. + * \param c the byte value to set. + * \param len the length, in bytes, to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); + +/** + * Initialize all 32-bit words of buffer of memory to a specific value. + * + * This function will set a buffer of `dwords` Uint32 values, pointed to by + * `dst`, to the value specified in `val`. + * + * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited + * to a range of 0-255. + * + * \param dst the destination memory region. Must not be NULL. + * \param val the Uint32 value to set. + * \param dwords the number of Uint32 values to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); /* Take advantage of compiler optimizations for memset */ @@ -960,18 +2575,255 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo #define SDL_memset memset #endif +/** + * Clear an object's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an object, not a pointer to an object, nor an array. + * + * \param x the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zerop + * \sa SDL_zeroa + */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) + +/** + * Clear an object's memory to zero, using a pointer. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires a pointer to an object, not an object itself, nor an array. + * + * \param x a pointer to the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) + +/** + * Clear an array's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the array size, so + * there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an array, not an object, nor a pointer to an object. + * + * \param x an array to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) + +/** + * Compare two buffers of memory. + * + * \param s1 the first buffer to compare. NULL is not permitted! + * \param s2 the second buffer to compare. NULL is not permitted! + * \param len the number of bytes to compare between the buffers. + * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is + * "greater than" s2, and zero if the buffers match exactly for `len` + * bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); +/** + * This works exactly like wcslen() but doesn't require access to a C runtime. + * + * Counts the number of wchar_t values in `wstr`, excluding the null + * terminator. + * + * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \returns the length (in wchar_t values, excluding the null terminator) of + * `wstr`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcsnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); + +/** + * This works exactly like wcsnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the + * null terminator. + * + * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * Also, `maxlen` is a count of wide characters, not bytes! + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \param maxlen The maximum amount of wide characters to count. + * \returns the length (in wide characters, excluding the null terminator) of + * `wstr` but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * Copy a wide string. + * + * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then + * appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` is 0, no wide characters are copied and no null terminator is + * written. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated wide string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcat + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \param src The second null-terminated wide string. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Allocate a copy of a wide string. + * + * This allocates enough space for a null-terminated copy of `wstr`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param wstr the string to copy. + * \returns a pointer to the newly-allocated wide string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); + +/** + * Search a wide string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); + +/** + * Search a wide string, up to n wide chars, for the first instance of a + * specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * value to end the string, or `maxlen` wide character have been examined. It + * is possible to use this function on a wide string without a null + * terminator. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \param maxlen the maximum number of wide characters to search in + * `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -989,7 +2841,7 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); @@ -1020,7 +2872,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); @@ -1050,7 +2902,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t * * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); @@ -1092,19 +2944,228 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); +/** + * This works exactly like strlen() but doesn't require access to a C runtime. + * + * Counts the bytes in `str`, excluding the null terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the length (in bytes, excluding the null terminator) of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); + +/** + * This works exactly like strnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null + * terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \param maxlen The maximum amount of bytes to count. + * \returns the length (in bytes, excluding the null terminator) of `src` but + * never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * Copy a string. + * + * This function copies up to `maxlen` - 1 characters from `src` to `dst`, + * then appends a null terminator. + * + * If `maxlen` is 0, no characters are copied and no null terminator is + * written. + * + * If you want to copy an UTF-8 string but need to ensure that multi-byte + * sequences are not truncated, consider using SDL_utf8strlcpy(). + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated string to copy. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param dst_bytes The length (in bytes) of the destination buffer. Must not + * be 0. + * \returns the number of bytes written, excluding the null terminator. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \param src The second null-terminated string. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of the + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Allocate a copy of a string. + * + * This allocates enough space for a null-terminated copy of `str`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); + +/** + * Allocate a copy of a string, up to n characters. + * + * This allocates enough space for a null-terminated copy of `str`, up to + * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into + * this space. + * + * If the string is longer than `maxlen` bytes, the returned string will be + * `maxlen` bytes long, plus a null-terminator character that isn't included + * in the count. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \param maxlen the maximum length of the copied string, not counting the + * null-terminator character. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); + +/** + * Reverse a string's contents. + * + * This reverses a null-terminated string in-place. Only the content of the + * string is reversed; the null-terminator character remains at the end of the + * reversed string. + * + * **WARNING**: This function reverses the _bytes_ of the string, not the + * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this + * will ruin the string data. You should only use this function on strings + * that are completely comprised of low ASCII characters. + * + * \param str the string to reverse. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -1122,7 +3183,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strlwr */ @@ -1143,34 +3204,592 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strupr */ extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); +/** + * Search a string for the first instance of a specific byte. + * + * The search ends once it finds the requested byte value, or a null + * terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the first instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); + +/** + * Search a string for the last instance of a specific byte. + * + * The search must go until it finds a null terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the last instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); + +/** + * Search a string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); + +/** + * Search a string, up to n bytes, for the first instance of a specific + * substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string, or `maxlen` bytes have been examined. It is + * possible to use this function on a string without a null terminator. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \param maxlen the maximum number of bytes to search in `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); + +/** + * Search a UTF-8 string for the first instance of a specific substring, + * case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); -extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr); + +/** + * This works exactly like strtok_r() but doesn't require access to a C + * runtime. + * + * Break a string up into a series of tokens. + * + * To start tokenizing a new string, `str` should be the non-NULL address of + * the string to start tokenizing. Future calls to get the next token from the + * same string should specify a NULL. + * + * Note that this function will overwrite pieces of `str` with null chars to + * split it into tokens. This function cannot be used with const/read-only + * strings! + * + * `saveptr` just needs to point to a `char *` that can be overwritten; SDL + * will use this to save tokenizing state between calls. It is initialized if + * `str` is non-NULL, and used to resume tokenizing when `str` is NULL. + * + * \param str the string to tokenize, or NULL to continue tokenizing. + * \param delim the delimiter string that separates tokens. + * \param saveptr pointer to a char *, used for ongoing state. + * \returns A pointer to the next token, or NULL if no tokens remain. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr); + +/** + * Count the number of codepoints in a UTF-8 string. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strlen(). + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \returns The length (in codepoints, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strnlen + * \sa SDL_strlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); + +/** + * Count the number of codepoints in a UTF-8 string, up to n bytes. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strnlen(). + * + * The counting stops at `bytes` bytes (not codepoints!). This seems + * counterintuitive, but makes it easy to express the total size of the + * string's buffer. + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \param bytes The maximum amount of bytes to count. + * \returns The length (in codepoints, excluding the null terminator) of `src` + * but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strlen + * \sa SDL_strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); +/** + * Convert an integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +/** + * Convert an unsigned integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_itoa + * \sa SDL_ultoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); + +/** + * Convert a long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ultoa + * \sa SDL_itoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); + +/** + * Convert an unsigned long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +#ifndef SDL_NOLONGLONG + +/** + * Convert a long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ulltoa + * \sa SDL_itoa + * \sa SDL_ltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); + +/** + * Convert an unsigned long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); +#endif + +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to + * `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +#ifndef SDL_NOLONGLONG + +/** + * Parse a `long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long long`, the result is + * clamped to the minimum and maximum representable `long long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long long`, or 0 if no number could be + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); +#endif + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. The handling of + * scientific and hexadecimal notation is unspecified. + * - Whether or not INF and NAN can be parsed is unspecified. + * - The precision of the result is unspecified. + * + * \param str the null-terminated string to read. Must not be NULL. + * \param endp if not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \returns the parsed `double`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /** @@ -1189,7 +3808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); @@ -1219,7 +3838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); @@ -1247,7 +3866,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); @@ -1287,20 +3906,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + /** * The Unicode REPLACEMENT CHARACTER codepoint. * - * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string - * with encoding errors. + * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they + * encounter a UTF-8 string with encoding errors. * * This tends to render as something like a question mark in most places. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * + * \sa SDL_StepBackUTF8 * \sa SDL_StepUTF8 */ #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD @@ -1346,10 +3984,41 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); +/** + * Decode a UTF-8 string in reverse, one Unicode codepoint at a time. + * + * This will go to the start of the previous Unicode codepoint in the string, + * move `*pstr` to that location and return that codepoint. + * + * If `*pstr` is already at the start of the string), it will not advance + * `*pstr` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameter each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT. + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param start a pointer to the beginning of the UTF-8 string. + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \returns the previous Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr); + /** * Convert a single Unicode codepoint to UTF-8. * @@ -1375,18 +4044,200 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); - +/** + * This works exactly like sscanf() but doesn't require access to a C runtime. + * + * Scan a string, matching a format string, converting each '%' item and + * storing it to pointers provided through variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); + +/** + * This works exactly like vsscanf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_sscanf(), except it takes a `va_list` instead + * of using `...` variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` of pointers to values to be filled in with scanned + * items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like snprintf() but doesn't require access to a C + * runtime. + * + * Format a string of up to `maxlen`-1 bytes, converting each '%' item with + * values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * bytes will be written at all. + * + * This function returns the number of _bytes_ (not _characters_) that should + * be written, excluding the null-terminator character. If this returns a + * number >= `maxlen`, it means the output string was truncated. A negative + * return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * This works exactly like swprintf() but doesn't require access to a C + * runtime. + * + * Format a wide string of up to `maxlen`-1 wchar_t values, converting each + * '%' item with values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide + * characters will be written at all. + * + * This function returns the number of _wide characters_ (not _codepoints_) + * that should be written, excluding the null-terminator character. If this + * returns a number >= `maxlen`, it means the output string was truncated. A + * negative return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the wide string into. Must not be NULL. + * \param maxlen the maximum wchar_t values to write, including the + * null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like vsnprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); + +/** + * This works exactly like vswprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_swprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum wide characters to write, including the + * null-terminator. + * \param fmt a printf-style format wide string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like asprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it allocates a buffer large + * enough to hold the output string on behalf of the caller. + * + * On success, this function returns the number of bytes (not characters) + * comprising the output string, not counting the null-terminator character, + * and sets `*strp` to the newly-allocated string. + * + * On error, this function returns a negative number, and the value of `*strp` + * is undefined. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * This works exactly like vasprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_asprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** @@ -1401,7 +4252,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR * \threadsafety This should be called on the same thread that calls * SDL_rand*() * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits @@ -1436,7 +4287,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_randf @@ -1459,7 +4310,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_rand @@ -1481,7 +4332,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf(void); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_randf @@ -1516,7 +4367,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits_r @@ -1543,7 +4394,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_bits_r * \sa SDL_rand_r @@ -1569,18 +4420,34 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_r * \sa SDL_randf_r */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); - #ifndef SDL_PI_D + +/** + * The value of Pi, as a double-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_F + */ #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ #endif + #ifndef SDL_PI_F + +/** + * The value of Pi, as a single-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_D + */ #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ #endif @@ -1606,7 +4473,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acosf * \sa SDL_asin @@ -1636,7 +4503,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acos * \sa SDL_asinf @@ -1666,7 +4533,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asinf * \sa SDL_acos @@ -1696,7 +4563,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asin * \sa SDL_acosf @@ -1728,7 +4595,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atanf * \sa SDL_atan2 @@ -1760,7 +4627,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan * \sa SDL_atan2f @@ -1796,7 +4663,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1832,7 +4699,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1858,7 +4725,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceilf * \sa SDL_floor @@ -1886,7 +4753,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceil * \sa SDL_floorf @@ -1915,7 +4782,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabs @@ -1941,7 +4808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabsf @@ -1968,7 +4835,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cosf * \sa SDL_acos @@ -1996,7 +4863,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cos * \sa SDL_acosf @@ -2029,7 +4896,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_expf * \sa SDL_log @@ -2061,7 +4928,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_exp * \sa SDL_logf @@ -2083,7 +4950,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabsf */ @@ -2104,7 +4971,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabs */ @@ -2128,7 +4995,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floorf * \sa SDL_ceil @@ -2156,7 +5023,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floor * \sa SDL_ceilf @@ -2184,7 +5051,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_truncf * \sa SDL_fmod @@ -2213,7 +5080,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_trunc * \sa SDL_fmodf @@ -2242,7 +5109,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmodf * \sa SDL_modf @@ -2272,7 +5139,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmod * \sa SDL_truncf @@ -2292,7 +5159,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinff */ @@ -2306,7 +5173,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinf */ @@ -2320,7 +5187,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnanf */ @@ -2334,7 +5201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnan */ @@ -2362,7 +5229,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_logf * \sa SDL_log10 @@ -2392,7 +5259,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log * \sa SDL_expf @@ -2421,7 +5288,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10f * \sa SDL_log @@ -2451,7 +5318,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10 * \sa SDL_logf @@ -2471,7 +5338,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modff * \sa SDL_trunc @@ -2491,7 +5358,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modf * \sa SDL_truncf @@ -2523,7 +5390,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_powf * \sa SDL_exp @@ -2555,7 +5422,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_pow * \sa SDL_expf @@ -2582,7 +5449,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_roundf * \sa SDL_lround @@ -2611,7 +5478,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_round * \sa SDL_lroundf @@ -2640,7 +5507,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lroundf * \sa SDL_round @@ -2669,7 +5536,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lround * \sa SDL_roundf @@ -2697,7 +5564,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbnf * \sa SDL_pow @@ -2722,7 +5589,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbn * \sa SDL_powf @@ -2749,7 +5616,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sinf * \sa SDL_asin @@ -2765,7 +5632,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * Range: `-1 <= y <= 1` * * This function operates on single-precision floating point values, use - * SDL_sinf for double-precision floats. + * SDL_sin for double-precision floats. * * This function may use a different approximation across different versions, * platforms and configurations. i.e, it can return a different value given @@ -2777,7 +5644,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sin * \sa SDL_asinf @@ -2805,7 +5672,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrtf */ @@ -2831,7 +5698,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrt */ @@ -2857,7 +5724,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tanf * \sa SDL_sin @@ -2887,7 +5754,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tan * \sa SDL_sinf @@ -2897,12 +5764,13 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); */ extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); -/* The SDL implementation of iconv() returns these error codes */ -#define SDL_ICONV_ERROR (size_t)-1 -#define SDL_ICONV_E2BIG (size_t)-2 -#define SDL_ICONV_EILSEQ (size_t)-3 -#define SDL_ICONV_EINVAL (size_t)-4 - +/** + * An opaque handle representing string encoding conversion state. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + */ typedef struct SDL_iconv_data_t *SDL_iconv_t; /** @@ -2914,7 +5782,7 @@ typedef struct SDL_iconv_data_t *SDL_iconv_t; * \returns a handle that must be freed with SDL_iconv_close, or * SDL_ICONV_ERROR on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_close @@ -2929,7 +5797,7 @@ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, * \param cd The character set conversion handle. * \returns 0 on success, or -1 on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_open @@ -2941,7 +5809,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * This function converts text between encodings, reading from and writing to * a buffer. * - * It returns the number of succesful conversions. + * It returns the number of succesful conversions on success. On error, + * SDL_ICONV_E2BIG is returned when the output buffer is too small, or + * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, + * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte sequence. On + * error, this is the location of the problematic input sequence. On + * success, this is the end of the input sequence. + * - inbytesleft will be set to the number of bytes left to convert, which + * will be 0 on success. + * - outbuf will point to the location where to store the next output byte. + * - outbytesleft will be set to the number of bytes left in the output + * buffer. * * \param cd The character set conversion context, created in * SDL_iconv_open(). @@ -2950,23 +5833,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * \param inbytesleft The number of bytes in the input buffer. * \param outbuf Address of variable that points to the output buffer. * \param outbytesleft The number of bytes in the output buffer. - * \returns the number of conversions on success, else SDL_ICONV_E2BIG is - * returned when the output buffer is too small, or SDL_ICONV_EILSEQ - * is returned when an invalid input sequence is encountered, or - * SDL_ICONV_EINVAL is returned when an incomplete input sequence is - * encountered. + * \returns the number of conversions on success, or a negative error code. * - * On exit: - * - * - inbuf will point to the beginning of the next multibyte - * sequence. On error, this is the location of the problematic - * input sequence. On success, this is the end of the input - * sequence. - inbytesleft will be set to the number of bytes left - * to convert, which will be 0 on success. - outbuf will point to - * the location where to store the next output byte. - outbytesleft - * will be set to the number of bytes left in the output buffer. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -2976,6 +5845,12 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); +#define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */ +#define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */ +#define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */ +#define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */ + + /** * Helper function to convert a string's encoding in one call. * @@ -2995,7 +5870,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, * \param inbytesleft the size of the input string _in bytes_. * \returns a new string, converted to the new encoding, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -3006,12 +5881,65 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *inbuf, size_t inbytesleft); -/* Some helper macros for common cases... */ +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) + /* force builds using Clang's static analysis tools to use literal C runtime here, since there are possibly tests that are ineffective otherwise. */ #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) @@ -3034,6 +5962,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include @@ -3073,6 +6004,7 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #define SDL_wcsncmp wcsncmp #define SDL_strcasecmp strcasecmp #define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk #define SDL_sscanf sscanf #define SDL_vsscanf vsscanf #define SDL_snprintf snprintf @@ -3082,29 +6014,27 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); /** * Multiply two integers, checking for overflow. * - * If `a * b` would overflow, return -1. + * If `a * b` would overflow, return false. * - * Otherwise store `a * b` via ret and return 0. + * Otherwise store `a * b` via ret and return true. * * \param a the multiplicand. * \param b the multiplier. - * \param ret on non-overflow output, stores the multiplication result. May + * \param ret on non-overflow output, stores the multiplication result, may * not be NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is multiplied without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) { if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; + return false; } *ret = a * b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION @@ -3112,60 +6042,72 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, /* This needs to be wrapped in an inline rather than being a direct #define, * because __builtin_mul_overflow() is type-generic, but we want to be * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_mul_overflow(a, b, ret) == 0); } -#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) #endif #endif /** * Add two integers, checking for overflow. * - * If `a + b` would overflow, return -1. + * If `a + b` would overflow, return false. * - * Otherwise store `a + b` via ret and return 0. + * Otherwise store `a + b` via ret and return true. * * \param a the first addend. * \param b the second addend. - * \param ret on non-overflow output, stores the addition result. May not be + * \param ret on non-overflow output, stores the addition result, may not be * NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is added without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) { if (b > SDL_SIZE_MAX - a) { - return -1; + return false; } *ret = a + b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION #if SDL_HAS_BUILTIN(__builtin_add_overflow) /* This needs to be wrapped in an inline rather than being a direct #define, * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_add_overflow(a, b, ret) == 0); } -#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) #endif #endif /* This is a generic function pointer which should be cast to the type you expect */ -#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) typedef void *SDL_FunctionPointer; #else typedef void (*SDL_FunctionPointer)(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_storage.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_storage.h index 91a90bc..8b89ace 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_storage.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_storage.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,222 @@ /** * # CategoryStorage * - * SDL storage container management. + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) { + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(data); + * } + * } + * } + * + * void ReadSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * + * void WriteSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(NULL, 0); + * if (title == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(title)) { + * SDL_Delay(1); + * } + * + * for (size_t i = 0; i < numFiles; i += 1) { + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) { + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * } + * + * SDL_CloseStorage(title); + * } + * + * void ReadSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) { + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * + * void WriteSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. */ #ifndef SDL_storage_h_ @@ -40,8 +255,6 @@ extern "C" { #endif -/* !!! FIXME: Don't let this ship without async R/W support!!! */ - /** * Function interface for SDL_Storage. * @@ -52,44 +265,61 @@ extern "C" { * It is not usually necessary to do this; SDL provides standard * implementations for many things you might expect to do with an SDL_Storage. * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_StorageInterface { + /* The version of this interface */ + Uint32 version; + /* Called when the storage is closed */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); /* Optional, returns whether the storage is currently ready for access */ - SDL_bool (SDLCALL *ready)(void *userdata); + bool (SDLCALL *ready)(void *userdata); /* Enumerate a directory, optional for write-only storage */ - SDL_bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); /* Get path information, optional for write-only storage */ - SDL_bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); /* Read a file from storage, optional for write-only storage */ - SDL_bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); /* Write a file to storage, optional for read-only storage */ - SDL_bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); /* Create a directory, optional for read-only storage */ - SDL_bool (SDLCALL *mkdir)(void *userdata, const char *path); + bool (SDLCALL *mkdir)(void *userdata, const char *path); /* Remove a file or empty directory, optional for read-only storage */ - SDL_bool (SDLCALL *remove)(void *userdata, const char *path); + bool (SDLCALL *remove)(void *userdata, const char *path); /* Rename a path, optional for read-only storage */ - SDL_bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); /* Copy a file, optional for read-only storage */ - SDL_bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); } SDL_StorageInterface; +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + /** * An abstract interface for filesystem access. * @@ -97,7 +327,7 @@ typedef struct SDL_StorageInterface * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create * an object with a custom implementation using SDL_OpenStorage. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Storage SDL_Storage; @@ -109,7 +339,7 @@ typedef struct SDL_Storage SDL_Storage; * \returns a title storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -132,7 +362,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *overr * \returns a user storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -156,7 +386,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, c * \returns a filesystem storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -176,16 +406,21 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * or SDL_OpenUserStorage(). * - * \param iface the function table to be used by this container. - * \param userdata the pointer that will be passed to the store interface. + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE * \sa SDL_ReadStorageFile * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -196,33 +431,33 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * Closes and frees a storage container. * * \param storage a storage container to close. - * \returns SDL_TRUE if the container was freed with no errors, SDL_FALSE - * otherwise; call SDL_GetError() for more information. Even if the - * function returns an error, the container data will be freed; the - * error is only for informational purposes. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenFileStorage * \sa SDL_OpenStorage * \sa SDL_OpenTitleStorage * \sa SDL_OpenUserStorage */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); /** * Checks if the storage container is ready to use. * - * This function should be called in regular intervals until it returns - * SDL_TRUE - however, it is not recommended to spinwait on this call, as the - * backend may depend on a synchronous message loop. + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. * * \param storage a storage container to query. - * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise. + * \returns true if the container is ready, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); /** * Query the size of a file within a storage container. @@ -230,34 +465,38 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); * \param storage a storage container to query. * \param path the relative path of the file to query. * \param length a pointer to be filled with the file's length. - * \returns SDL_TRUE if the file could be queried or SDL_FALSE on failure; - * call SDL_GetError() for more information. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); /** * Synchronously read a file from a storage container into a client-provided * buffer. * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * * \param storage a storage container to read from. * \param path the relative path of the file to read. * \param destination a client-provided buffer to read the file into. * \param length the length of the destination buffer. - * \returns SDL_TRUE if the file was read or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageFileSize * \sa SDL_StorageReady * \sa SDL_WriteStorageFile */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); /** * Synchronously write a file from client memory into a storage container. @@ -266,64 +505,73 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, c * \param path the relative path of the file to write. * \param source a client-provided buffer to write from. * \param length the length of the source buffer. - * \returns SDL_TRUE if the file was written or SDL_FALSE on failure; call + * \returns true if the file was written or false on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageSpaceRemaining * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); /** * Create a directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); /** * Enumerate a directory in a storage container through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); /** * Rename a file or directory in a writable storage container. @@ -331,14 +579,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Copy a file in a writable storage container. @@ -346,14 +594,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Get information about a filesystem path in a storage container. @@ -362,14 +610,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, c * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); /** * Queries the remaining space in a storage container. @@ -377,7 +625,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage * \param storage a storage container to query. * \returns the amount of remaining space, in bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -401,8 +649,11 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param pattern the pattern that files in the directory must match. Can be * NULL. * \param flags `SDL_GLOB_*` bitflags that affect this search. @@ -417,7 +668,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * \threadsafety It is safe to call this function from any thread, assuming * the `storage` object is thread-safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_surface.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_surface.h index aafe574..0752f53 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_surface.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_surface.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,19 @@ /** * # CategorySurface * - * SDL_Surface definition and management functions. + * SDL surfaces are buffers of pixels in system RAM. These are useful for + * passing around and manipulating images that are not stored in GPU memory. + * + * SDL_Surface makes serious efforts to manage images in various formats, and + * provides a reasonable toolbox for transforming the data, including copying + * between surfaces, filling rectangles in the image data, etc. + * + * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not + * provide loaders for various other file formats, but there are several + * excellent external libraries that do, including its own satellite library, + * SDL_image: + * + * https://github.com/libsdl-org/SDL_image */ #ifndef SDL_surface_h_ @@ -47,7 +59,7 @@ extern "C" { * * These are generally considered read-only. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SurfaceFlags; @@ -59,14 +71,14 @@ typedef Uint32 SDL_SurfaceFlags; /** * Evaluates to true if the surface needs to be locked before access. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MUSTLOCK(S) ((((S)->flags & SDL_SURFACE_LOCK_NEEDED)) == SDL_SURFACE_LOCK_NEEDED) /** * The scaling mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ScaleMode { @@ -77,7 +89,7 @@ typedef enum SDL_ScaleMode /** * The flip mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlipMode { @@ -86,8 +98,7 @@ typedef enum SDL_FlipMode SDL_FLIP_VERTICAL /**< flip vertically */ } SDL_FlipMode; -/* Internal surface data */ -typedef struct SDL_SurfaceData SDL_SurfaceData; +#ifndef SDL_INTERNAL /** * A collection of pixels used in software blitting. @@ -104,22 +115,32 @@ typedef struct SDL_SurfaceData SDL_SurfaceData; * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * - * \since This struct is available since SDL 3.0.0. + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface */ -typedef struct SDL_Surface +struct SDL_Surface { - SDL_SurfaceFlags flags; /**< Read-only */ - SDL_PixelFormat format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-only pointer, writable pixels if non-NULL */ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ int refcount; /**< Application reference count, used when freeing surface */ - SDL_SurfaceData *internal; /**< Private */ - -} SDL_Surface; + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ +typedef struct SDL_Surface SDL_Surface; /** * Allocate a new surface with a specific pixel format. @@ -132,7 +153,7 @@ typedef struct SDL_Surface * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurfaceFrom * \sa SDL_DestroySurface @@ -160,7 +181,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurface(int width, int heigh * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -174,9 +195,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurfaceFrom(int width, int h * * \param surface the SDL_Surface to free. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_CreateStackSurface * \sa SDL_CreateSurface * \sa SDL_CreateSurfaceFrom */ @@ -206,7 +226,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface); @@ -221,16 +241,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac * interpreted in color operations. * * \param surface the SDL_Surface structure to update. - * \param colorspace an SDL_ColorSpace value describing the surface + * \param colorspace an SDL_Colorspace value describing the surface * colorspace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); /** * Get the colorspace used by a surface. @@ -243,7 +263,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surfa * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if * the surface is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorspace */ @@ -271,7 +291,7 @@ extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface * the surface didn't have an index format); call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -284,15 +304,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface * * * \param surface the SDL_Surface structure to update. * \param palette the SDL_Palette structure to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); /** * Get the palette used by a surface. @@ -301,7 +321,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, * \returns a pointer to the palette used by the surface, or NULL if there is * no palette used. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfacePalette */ @@ -321,31 +341,30 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \param surface the SDL_Surface structure to update. * \param image a pointer to an alternate SDL_Surface to associate with this * surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages * \sa SDL_SurfaceHasAlternateImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); /** * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true if alternate versions are available or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); /** * Get an array including all versions of a surface. @@ -364,7 +383,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface * * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -380,7 +399,7 @@ extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *sur * * \param surface the SDL_Surface structure to update. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_GetSurfaceImages @@ -401,22 +420,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s * format of the surface will not change. * * \param surface the SDL_Surface structure to be locked. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockSurface(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); /** * Release a surface after directly accessing the pixels. * * \param surface the SDL_Surface structure to be unlocked. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSurface */ @@ -429,18 +448,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * will result in a memory leak. * * \param src the data stream for the surface. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); /** * Load a BMP image from a file. @@ -452,7 +471,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP_IO @@ -471,17 +490,17 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); * * \param surface the SDL_Surface structure containing the image to be saved. * \param dst a data stream to save to. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, - * even in the case of an error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closeio if true, calls SDL_CloseIO() on `dst` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, SDL_bool closeio); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); /** * Save a surface to a file. @@ -494,15 +513,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IO * * \param surface the SDL_Surface structure containing the image to be saved. * \param file a file to save to. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); /** * Set the RLE acceleration hint for a surface. @@ -511,32 +530,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const cha * the surface must be locked before directly accessing the pixels. * * \param surface the SDL_Surface structure to optimize. - * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable - * it. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable RLE acceleration, false to disable it. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface * \sa SDL_LockSurface * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); /** * Returns whether the surface is RLE enabled. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. + * \returns true if the surface is RLE enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceRLE */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); /** * Set the color key (transparent pixel) in a surface. @@ -549,34 +567,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * SDL_MapRGB(). * * \param surface the SDL_Surface structure to update. - * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color - * key. + * \param enabled true to enable color key, false to disable color key. * \param key the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorKey * \sa SDL_SetSurfaceRLE * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); /** * Returns whether the surface has a color key. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. + * \returns true if the surface has a color key, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); /** * Get the color key (transparent pixel) for a surface. @@ -584,19 +601,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface * The color key is a pixel of the format used by the surface, as generated by * SDL_MapRGB(). * - * If the surface doesn't have color key enabled this function returns -1. + * If the surface doesn't have color key enabled this function returns false. * * \param surface the SDL_Surface structure to query. * \param key a pointer filled in with the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); /** * Set an additional color value multiplied into blit operations. @@ -611,15 +628,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface * \param r the red color value multiplied into blit operations. * \param g the green color value multiplied into blit operations. * \param b the blue color value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); /** @@ -629,15 +646,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); /** * Set an additional alpha value used in blit operations. @@ -649,30 +666,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param alpha the alpha value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); /** * Get the additional alpha value used in blit operations. * * \param surface the SDL_Surface structure to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); /** * Set the blend mode used for blit operations. @@ -683,28 +700,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); /** * Get the blend mode used for blit operations. * * \param surface the SDL_Surface structure to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); /** * Set the clipping rectangle for a surface. @@ -718,14 +735,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surfac * \param surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); /** * Get the clipping rectangle for a surface. @@ -737,26 +754,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for * the surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); /** * Flip a surface vertically or horizontally. * * \param surface the surface to flip. * \param flip the direction to flip. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); /** * Creates a new surface identical to the existing surface. @@ -770,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_F * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -789,7 +806,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surf * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -814,7 +831,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface, * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurfaceAndColorspace * \sa SDL_DestroySurface @@ -840,10 +857,9 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurface - * \sa SDL_ConvertSurface * \sa SDL_DestroySurface */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props); @@ -859,14 +875,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Su * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixelsAndColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); /** * Copy a block of pixels of one format and colorspace to another format and @@ -875,27 +891,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SD * \param width the width of the block to copy, in pixels. * \param height the height of the block to copy, in pixels. * \param src_format an SDL_PixelFormat value of the `src` pixels format. - * \param src_colorspace an SDL_ColorSpace value describing the colorspace of + * \param src_colorspace an SDL_Colorspace value describing the colorspace of * the `src` pixels. * \param src_properties an SDL_PropertiesID with additional source color * properties, or 0. * \param src a pointer to the source pixels. * \param src_pitch the pitch of the source pixels, in bytes. * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. - * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of * the `dst` pixels. * \param dst_properties an SDL_PropertiesID with additional destination color * properties, or 0. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixels */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); /** * Premultiply the alpha on a block of pixels. @@ -910,14 +926,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, i * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with premultiplied pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); /** * Premultiply the alpha in a surface. @@ -925,14 +941,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, * This is safe to use with src == dst, but not for other overlapping areas. * * \param surface the surface to modify. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); /** * Clear a surface with a specific color, with floating point precision. @@ -947,12 +963,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *su * \param g the green component of the pixel, normally in the range 0-1. * \param b the blue component of the pixel, normally in the range 0-1. * \param a the alpha component of the pixel, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); /** * Perform a fast fill of a rectangle with a specific color. @@ -970,14 +986,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, floa * \param rect the SDL_Rect structure representing the rectangle to fill, or * NULL to fill the entire surface. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); /** * Perform a fast fill of a set of rectangles with a specific color. @@ -995,22 +1011,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const * \param rects an array of SDL_Rects representing the rectangles to fill. * \param count the number of rectangles in the array. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); /** - * Performs a fast blit from the source surface to the destination surface. + * Performs a fast blit from the source surface to the destination surface + * with clipping. * - * This assumes that the source and destination rectangles are the same size. * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or - * `dst`) is copied. The final blit rectangles are saved in `srcrect` and - * `dstrect` after all clipping is performed. + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. + * + * The final blit rectangles are saved in `srcrect` and `dstrect` after all + * clipping is performed. * * The blit function should not be called on a locked surface. * @@ -1066,18 +1084,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, cons * height are ignored, and are copied from `srcrect`. If you * want a specific width and height, you should use * SDL_BlitSurfaceScaled(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform low-level surface blitting only. @@ -1091,18 +1109,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit to a destination surface, which may be of a different @@ -1116,18 +1134,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, * the destination surface, or NULL to fill the entire * destination surface. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform low-level surface scaled blitting only. @@ -1142,18 +1160,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, con * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform a tiled blit to a destination surface, which may be of a different @@ -1168,18 +1186,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled and tiled blit to a destination surface, which may be of a @@ -1198,18 +1216,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, cons * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit using the 9-grid algorithm to a destination surface, @@ -1235,18 +1253,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface * * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Map an RGB triple to an opaque pixel value for a surface. @@ -1272,7 +1290,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, cons * \param b the blue component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGBA */ @@ -1303,7 +1321,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 * \param a the alpha component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGB */ @@ -1329,12 +1347,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint * ignore this channel. * \param a a pointer filled in with the alpha channel, 0-255, or NULL to * ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Retrieves a single pixel from a surface. @@ -1353,12 +1371,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, * 0-1, or NULL to ignore this channel. * \param a a pointer filled in with the alpha channel, normally in the range * 0-1, or NULL to ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); /** * Writes a single pixel to a surface. @@ -1376,12 +1394,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surf * \param g the green channel value, 0-255. * \param b the blue channel value, 0-255. * \param a the alpha channel value, 0-255. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Writes a single pixel to a surface. @@ -1396,12 +1414,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, * \param g the green channel value, normally in the range 0-1. * \param b the blue channel value, normally in the range 0-1. * \param a the alpha channel value, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_system.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_system.h index 17ac0a1..294089f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_system.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_system.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,13 @@ /** * # CategorySystem * - * Platform-specific SDL API functions. + * Platform-specific SDL API functions. These are functions that deal with + * needs of specific operating systems, that didn't make sense to offer as + * platform-independent, generic APIs. + * + * Most apps can make do without these functions, but they can be useful for + * integrating with other parts of a specific system, adding platform-specific + * polish to an app, or solving problems that only affect one target. */ #ifndef SDL_system_h_ @@ -31,7 +37,6 @@ #include #include #include -#include #include #include @@ -44,16 +49,15 @@ extern "C" { /* * Platform specific functions for Windows */ -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) typedef struct tagMSG MSG; /** * A callback to be used with SDL_SetWindowsMessageHook. * - * This callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * This callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * As this is processing a message directly from the Windows event loop, this * callback should do the minimum required work and return quickly. @@ -61,36 +65,35 @@ typedef struct tagMSG MSG; * \param userdata the app-defined pointer provided to * SDL_SetWindowsMessageHook. * \param msg a pointer to a Win32 event structure to process. - * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it. + * \returns true to let event continue on, false to drop it. * * \threadsafety This may only be called (by SDL) from the thread handling the * Windows event loop. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetWindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ -typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); /** * Set a callback for every Windows message, run before TranslateMessage(). * - * The callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_WindowsMessageHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) @@ -104,14 +107,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo * \returns the D3D9 adapter index on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ - -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) - /** * Get the DXGI Adapter and Output indices for the specified display. * @@ -122,33 +121,55 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displ * \param displayID the instance of the display to query. * \param adapterIndex a pointer to be filled in with the adapter index. * \param outputIndex a pointer to be filled in with the output index. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + /* * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _XEvent XEvent; -typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); + +/** + * A callback to be used with SDL_SetX11EventHook. + * + * This callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * As this is processing an event directly from the X11 event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to SDL_SetX11EventHook. + * \param xevent a pointer to an Xlib XEvent union to process. + * \returns true to let event continue on, false to drop it. + * + * \threadsafety This may only be called (by SDL) from the thread handling the + * X11 event loop. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetX11EventHook + */ +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** * Set a callback for every X11 event. * - * The callback may modify the event, and should return SDL_TRUE if the event - * should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_X11EventHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); @@ -162,12 +183,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, * * \param threadID the Unix thread ID to change priority of. * \param priority the new, Unix-specific, priority value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); /** * Sets the priority (not nice level) and scheduling policy for a thread. @@ -178,12 +199,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, * \param sdlPriority the new SDL_ThreadPriority value. * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, * SCHED_OTHER, etc...). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); #endif /* SDL_PLATFORM_LINUX */ @@ -204,7 +225,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 * \param userdata what was passed as `callbackParam` to * SDL_SetiOSAnimationCallback as `callbackParam`. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ @@ -240,27 +261,27 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSEventPump */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); /** * Use this function to enable or disable the SDL event pump on Apple iOS. * * This function is only available on Apple iOS. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. + * \param enabled true to enable the event pump, false to disable it. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); #endif /* SDL_PLATFORM_IOS */ @@ -286,7 +307,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidActivity */ @@ -311,7 +332,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidJNIEnv */ @@ -349,43 +370,34 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); * * \returns the Android API level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - /** * Query if the application is running on a Chromebook. * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * \returns true if this is a Chromebook, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); /** * Query if the application is running on a Samsung DeX docking station. * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * \returns true if this is a DeX docking station, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); /** * Trigger the Android system back button behavior. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); @@ -393,9 +405,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * See the official Android developer guide for more information: * http://developer.android.com/guide/topics/data/data-storage.html * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 + +/** + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -414,9 +433,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \returns the path used for internal storage or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidExternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void); @@ -431,7 +451,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void) * \returns the current state of external storage, or 0 if external storage is * currently unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStoragePath */ @@ -453,9 +473,11 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); * \returns the path used for external storage for this application on success * or NULL on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void); @@ -474,12 +496,25 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) * \returns the path used for caches for this application on success or NULL * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidExternalStoragePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - -typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted); +/** + * Callback that presents a response from a SDL_RequestAndroidPermission call. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param permission the Android-specific permission name that was requested. + * \param granted true if permission is granted, false if denied. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RequestAndroidPermission + */ +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** * Request permissions at runtime, asynchronously. @@ -500,18 +535,22 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * like memory running out. Normally there will be a yes or no to the request * through the callback. * + * For the `permission` parameter, choose a value from here: + * + * https://developer.android.com/reference/android/Manifest.permission + * * \param permission the permission to request. * \param cb the callback to trigger when the request has a response. * \param userdata an app-controlled pointer that is passed to the callback. - * \returns SDL_TRUE if the request was submitted, SDL_FALSE if there was an - * error submitting. The result of the request is only ever reported + * \returns true if the request was submitted, false if there was an error + * submitting. The result of the request is only ever reported * through the callback, not this return value. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); /** * Shows an Android toast notification. @@ -532,14 +571,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *pe * \param gravity where the notification should appear on the screen. * \param xoffset set this parameter only when gravity >=0. * \param yoffset set this parameter only when gravity >=0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); /** * Send a user command to SDLActivity. @@ -548,111 +587,63 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, i * * \param command user command that must be greater or equal to 0x8000. * \param param user parameter. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); #endif /* SDL_PLATFORM_ANDROID */ -/* - * Platform specific functions for WinRT - */ -#ifdef SDL_PLATFORM_WINRT - -/** - * WinRT / Windows Phone path types - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_Path -{ - /** The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily(); - -#endif /* SDL_PLATFORM_WINRT */ - /** * Query if the current device is a tablet. * - * If SDL can't determine this, it will return SDL_FALSE. + * If SDL can't determine this, it will return false. * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * \returns true if the device is a tablet, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_Sandbox +{ + SDL_SANDBOX_NONE = 0, + SDL_SANDBOX_UNKNOWN_CONTAINER, + SDL_SANDBOX_FLATPAK, + SDL_SANDBOX_SNAP, + SDL_SANDBOX_MACOS +} SDL_Sandbox; + +/** + * Get the application sandbox environment, if any. + * + * \returns the application sandbox environment or SDL_SANDBOX_NONE if the + * application is not running in a sandbox environment. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void); + /* Functions used by iOS app delegates to notify SDL about state changes. */ @@ -669,7 +660,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); @@ -686,7 +677,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); @@ -703,7 +694,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); @@ -720,7 +711,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); @@ -737,7 +728,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); @@ -754,7 +745,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); @@ -773,7 +764,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); #endif @@ -794,12 +785,12 @@ typedef struct XUser *XUserHandle; * leak. * * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); /** * Gets a reference to the default user handle for GDK. @@ -809,12 +800,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTa * * \param outUserHandle a pointer to be filled in with the default user * handle. - * \returns SDL_TRUE if success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); #endif diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_thread.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_thread.h index 0fdc8a0..277535f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_thread.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_thread.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,19 @@ /** * # CategoryThread * - * SDL thread management routines. + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. */ #include @@ -34,9 +46,8 @@ /* Thread synchronization primitives */ #include -#include -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +#if defined(SDL_PLATFORM_WINDOWS) #include /* _beginthreadex() and _endthreadex() */ #endif @@ -51,7 +62,7 @@ extern "C" { * * These are opaque data. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -65,7 +76,7 @@ typedef struct SDL_Thread SDL_Thread; * application will operate on, but having a way to uniquely identify a thread * can be useful at times. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetThreadID * \sa SDL_GetCurrentThreadID @@ -78,7 +89,7 @@ typedef Uint64 SDL_ThreadID; * 0 is the invalid ID. An app can create these and then set data for these * IDs that is unique to each thread. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetTLS * \sa SDL_SetTLS @@ -90,11 +101,11 @@ typedef SDL_AtomicInt SDL_TLSID; * * SDL will make system changes as necessary in order to apply the thread * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, @@ -103,13 +114,30 @@ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_TIME_CRITICAL } SDL_ThreadPriority; +/** + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + */ +typedef enum SDL_ThreadState +{ + SDL_THREAD_UNKNOWN, /**< The thread is not valid */ + SDL_THREAD_ALIVE, /**< The thread is currently running */ + SDL_THREAD_DETACHED, /**< The thread is detached and can't be waited on */ + SDL_THREAD_COMPLETE /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} SDL_ThreadState; + /** * The function passed to SDL_CreateThread() as the new thread's entry point. * * \param data what was passed as `data` to SDL_CreateThread(). * \returns a value that can be reported through SDL_WaitThread(). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -179,7 +207,7 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThreadWithProperties * \sa SDL_WaitThread @@ -245,7 +273,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -263,7 +291,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop /* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ #ifndef SDL_WIKI_DOCUMENTATION_SECTION -# if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +# if defined(SDL_PLATFORM_WINDOWS) # ifndef SDL_BeginThreadFunction # define SDL_BeginThreadFunction _beginthreadex # endif @@ -300,7 +328,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -314,7 +342,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunct * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -334,7 +362,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S * \returns a pointer to a UTF-8 string that names the specified thread, or * NULL if it doesn't have a name. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); @@ -350,7 +378,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); * * \returns the ID of the current thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetThreadID */ @@ -367,7 +395,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentThreadID */ @@ -381,25 +409,25 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * an administrator account. Be prepared for this to fail. * * \param priority the SDL_ThreadPriority to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); /** * Wait for a thread to finish. * - * Threads that haven't been detached will remain (as a "zombie") until this - * function cleans them up. Not doing so is a resource leak. + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. * * Once a thread has been cleaned up through this function, the SDL_Thread * that references it becomes invalid and should not be referenced again. As * such, only one thread may call SDL_WaitThread() on another. * - * The return code for the thread function is placed in the area pointed to by - * `status`, if `status` is not NULL. + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. * * You may not wait on a thread that has been used in a call to * SDL_DetachThread(). Use either that function or this one, but not both, or @@ -412,17 +440,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority pr * * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. - * \param status pointer to an integer that will receive the value returned - * from the thread function by its 'return', or NULL to not - * receive such value back. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_DetachThread */ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status); +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *thread); + /** * Let a thread clean up on exit without intervention. * @@ -452,7 +493,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status) * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -468,7 +509,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread *thread); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -481,7 +522,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetTLS(SDL_TLSID *id); * * \param value a pointer previously handed to SDL_SetTLS. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -504,16 +545,16 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * \param value the value to associate with the ID for the current thread. * \param destructor a function called when the thread exits, to free the * value, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTLS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. @@ -524,7 +565,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CleanupTLS(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_time.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_time.h index 86c1fad..b6d3f6d 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_time.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_time.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ freely, subject to the following restrictions: * # CategoryTime * * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. */ #include @@ -41,7 +49,7 @@ extern "C" { * A structure holding a calendar date and time broken down into its * components. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DateTime { @@ -59,7 +67,7 @@ typedef struct SDL_DateTime /** * The preferred date format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -73,7 +81,7 @@ typedef enum SDL_DateFormat /** * The preferred time format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -95,24 +103,24 @@ typedef enum SDL_TimeFormat * format, may be NULL. * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * format, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); /** * Gets the current value of the system realtime clock in nanoseconds since * Jan 1, 1970 in Universal Coordinated Time (UTC). * * \param ticks the SDL_Time to hold the returned tick count. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); /** * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in @@ -123,12 +131,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \param localTime the resulting SDL_DateTime will be expressed in local time * if true, otherwise it will be in Universal Coordinated * Time (UTC). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime); +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); /** * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. @@ -138,12 +146,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_Date * * \param dt the source SDL_DateTime. * \param ticks the resulting SDL_Time. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); /** * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals @@ -157,7 +165,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, * \param dwHighDateTime a pointer filled in with the high portion of the * Windows FILETIME value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); @@ -172,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow * \param dwHighDateTime the high portion of the Windows FILETIME value. * \returns the converted SDL time. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); @@ -184,7 +192,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * \returns the number of days in the requested month or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); @@ -197,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \returns the day of year [0-365] if the date is valid or -1 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); @@ -210,7 +218,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or * -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_timer.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_timer.h index 9d05161..cf94881 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_timer.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_timer.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,20 @@ /** * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. */ #include @@ -38,16 +51,137 @@ extern "C" { #endif /* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_US 1000 + +/** + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND) + +/** + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND) + +/** + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS) + +/** + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS) + +/** + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US) + +/** + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) /** @@ -56,7 +190,9 @@ extern "C" { * \returns an unsigned 64-bit value representing the number of milliseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); @@ -66,7 +202,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); * \returns an unsigned 64-bit value representing the number of nanoseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); @@ -81,7 +219,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); * * \returns the current counter value. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceFrequency */ @@ -92,7 +232,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); * * \returns a platform-specific count per second. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceCounter */ @@ -107,10 +249,33 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * * \param ms the number of milliseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); + /** * Wait a specified number of nanoseconds before returning. * @@ -120,14 +285,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * * \param ns the number of nanoseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS */ -extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); +extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); /** * Definition of the timer ID type. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_TimerID; @@ -151,7 +321,7 @@ typedef Uint32 SDL_TimerID; * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimer */ @@ -160,8 +330,6 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimer() call and should return the next * timer interval. If the value returned from the callback is 0, the timer is @@ -188,7 +356,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimerNS * \sa SDL_RemoveTimer @@ -215,7 +383,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimerNS */ @@ -224,8 +392,6 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimerNS() call and should return the * next timer interval. If the value returned from the callback is 0, the @@ -252,7 +418,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer * \sa SDL_RemoveTimer @@ -263,14 +429,16 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * Remove a timer created with SDL_AddTimer(). * * \param id the ID of the timer to remove. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_touch.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_touch.h index 6889f36..64845a1 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_touch.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_touch.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryTouch * - * SDL touch management. + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. */ #ifndef SDL_touch_h_ @@ -31,7 +42,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -39,25 +49,53 @@ extern "C" { #endif +/** + * A unique ID for a touch device. + * + * This ID is valid for the time the device is connected to the system, and is + * never reused for the lifetime of the application. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_TouchID; + +/** + * A unique ID for a single finger on a touch device. + * + * This ID is valid for the time the finger (stylus, etc) is touching and will + * be unique for all fingers currently in contact, so this ID tracks the + * lifetime of a single continuous touch. This value may represent an index, a + * pointer, or some other unique ID, depending on the platform. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_FingerID; +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_TouchDeviceType { SDL_TOUCH_DEVICE_INVALID = -1, - SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ + SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */ } SDL_TouchDeviceType; /** * Data about a single finger in a multitouch event. * - * Each touch even is a collection of fingers that are simultaneously in + * Each touch event is a collection of fingers that are simultaneously in * contact with the touch device (so a "touch" can be a "multitouch," in * reality), and this struct reports details of the specific fingers. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetTouchFingers */ @@ -69,10 +107,18 @@ typedef struct SDL_Finger float pressure; /**< the quantity of pressure applied, normalized (0...1) */ } SDL_Finger; -/* Used as the device ID for mouse events simulated with touch input */ +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) -/* Used as the SDL_TouchID for touch events simulated with mouse input */ +/** + * The SDL_TouchID for touch events simulated with mouse input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) @@ -89,7 +135,7 @@ typedef struct SDL_Finger * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); @@ -100,7 +146,7 @@ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); * \returns touch device name, or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID); @@ -110,7 +156,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touc * \param touchID the ID of a touch device. * \returns touch device type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); @@ -125,7 +171,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_tray.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_tray.h new file mode 100644 index 0000000..0b05db2 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryTray + * + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. + */ + +#ifndef SDL_tray_h_ +#define SDL_tray_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Tray SDL_Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayMenu SDL_TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayEntry SDL_TrayEntry; + +/** + * Flags that control the creation of system tray entries. + * + * Some of these flags are required; exactly one of them must be specified at + * the time a tray entry is created. Other flags are optional; zero or more of + * those can be OR'ed together with the required flag. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +typedef Uint32 SDL_TrayEntryFlags; + +#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */ +#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */ +#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */ +#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */ +#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */ + +/** + * A callback that is invoked when a tray entry is selected. + * + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param entry the tray entry that was selected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTrayEntryCallback + */ +typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); + +/** + * Create an icon to be placed in the operating system's tray, or equivalent. + * + * Many platforms advise not using a system tray unless persistence is a + * necessary feature. Avoid needlessly creating a tray icon, as the user may + * feel like it clutters their interface. + * + * Using tray icons require the video subsystem. + * + * \param icon a surface to be used as icon. May be NULL. + * \param tooltip a tooltip to be displayed when the mouse hovers the icon in + * UTF-8 encoding. Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenu + * \sa SDL_DestroyTray + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip); + +/** + * Updates the system tray icon's icon. + * + * \param tray the tray icon to be updated. + * \param icon the new icon. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon); + +/** + * Updates the system tray icon's tooltip. + * + * \param tray the tray icon to be updated. + * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip); + +/** + * Create a menu for a system tray. + * + * This should be called at most once per tray icon. + * + * This function does the same thing as SDL_CreateTraySubmenu(), except that + * it takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_GetTrayMenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); + +/** + * Create a submenu for a system tray entry. + * + * This should be called at most once per tray entry. + * + * This function does the same thing as SDL_CreateTrayMenu, except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTraySubmenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry); + +/** + * Gets a previously created tray menu. + * + * You should have called SDL_CreateTrayMenu() on the tray object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTraySubmenu(), except that it + * takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_CreateTrayMenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); + +/** + * Gets a previously created tray entry submenu. + * + * You should have called SDL_CreateTraySubmenu() on the entry object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTrayMenu(), except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_CreateTraySubmenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry); + +/** + * Returns a list of entries in the menu, in order. + * + * \param menu The menu to get entries from. + * \param size An optional pointer to obtain the number of entries in the + * menu. + * \returns a NULL-terminated list of entries within the given menu. The + * pointer becomes invalid when any function that inserts or deletes + * entries in the menu is called. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveTrayEntry + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size); + +/** + * Removes a tray entry. + * + * \param entry The entry to be deleted. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); + +/** + * Insert a tray entry at a given position. + * + * If label is NULL, the entry will be a separator. Many functions won't work + * for an entry that is a separator. + * + * An entry does not need to be destroyed; it will be destroyed with the tray. + * + * \param menu the menu to append the entry to. + * \param pos the desired position for the new entry. Entries at or following + * this place will be moved. If pos is -1, the entry is appended. + * \param label the text to be displayed on the entry, in UTF-8 encoding, or + * NULL for a separator. + * \param flags a combination of flags, some of which are mandatory. + * \returns the newly created entry, or NULL if pos is out of bounds. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TrayEntryFlags + * \sa SDL_GetTrayEntries + * \sa SDL_RemoveTrayEntry + * \sa SDL_GetTrayEntryParent + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags); + +/** + * Sets the label of an entry. + * + * An entry cannot change between a separator and an ordinary entry; that is, + * it is not possible to set a non-NULL label on an entry that has a NULL + * label (separators), or to set a NULL label to an entry that has a non-NULL + * label. The function will silently fail if that happens. + * + * \param entry the entry to be updated. + * \param label the new label for the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryLabel + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label); + +/** + * Gets the label of an entry. + * + * If the returned value is NULL, the entry is a separator. + * + * \param entry the entry to be read. + * \returns the label of the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryLabel + */ +extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be updated. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryChecked + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked); + +/** + * Gets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be read. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryChecked + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is enabled. + * + * \param entry the entry to be updated. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled); + +/** + * Gets whether or not an entry is enabled. + * + * \param entry the entry to be read. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); + +/** + * Sets a callback to be invoked when the entry is selected. + * + * \param entry the entry to be updated. + * \param callback a callback to be invoked when the entry is selected. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata); + +/** + * Simulate a click on a tray entry. + * + * \param entry The entry to activate. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); + +/** + * Gets the menu containing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry); + +/** + * Gets the entry for which the menu is a submenu, if the current menu is a + * submenu. + * + * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent entry. + * \returns the parent entry, or NULL if this menu is not a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTraySubmenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu); + +/** + * Gets the tray for which this menu is the first-level menu, if the current + * menu isn't a submenu. + * + * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent enttrayry. + * \returns the parent tray, or NULL if this menu is a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); + +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_version.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_version.h index c0f518d..55014e3 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_version.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_version.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -30,7 +30,6 @@ #define SDL_version_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -43,7 +42,7 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 3. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MAJOR_VERSION 3 @@ -52,18 +51,18 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 2. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MINOR_VERSION 1 +#define SDL_MINOR_VERSION 2 /** * The current micro (or patchlevel) version of the SDL headers. * * If this were SDL version 3.2.1, this value would be 1. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MICRO_VERSION 2 +#define SDL_MICRO_VERSION 0 /** * This macro turns the version numbers into a numeric value. @@ -74,7 +73,7 @@ extern "C" { * \param minor the minorversion number. * \param patch the patch version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM(major, minor, patch) \ ((major) * 1000000 + (minor) * 1000 + (patch)) @@ -86,7 +85,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) @@ -97,7 +96,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) @@ -108,14 +107,16 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) /** * This is the version number macro for the current SDL version. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion */ #define SDL_VERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION) @@ -123,7 +124,7 @@ extern "C" { /** * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ (SDL_VERSION >= SDL_VERSIONNUM(X, Y, Z)) @@ -140,7 +141,7 @@ extern "C" { * * \returns the version of the linked library. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRevision */ @@ -166,7 +167,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); * \returns an arbitrary string, uniquely identifying the exact revision of * the SDL library in use. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVersion */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_video.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_video.h index 7cce828..a7afc32 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_video.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_video.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,28 @@ /** * # CategoryVideo * - * SDL video functions. + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). */ #ifndef SDL_video_h_ @@ -49,7 +70,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_DisplayID; @@ -58,7 +79,7 @@ typedef Uint32 SDL_DisplayID; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_WindowID; @@ -82,7 +103,7 @@ typedef Uint32 SDL_WindowID; /** * System theme. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemTheme { @@ -91,13 +112,21 @@ typedef enum SDL_SystemTheme SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ } SDL_SystemTheme; -/* Internal display mode data */ +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** * The structure that defines a display mode. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetFullscreenDisplayModes * \sa SDL_GetDesktopDisplayMode @@ -123,7 +152,7 @@ typedef struct SDL_DisplayMode /** * Display orientation values; the way a display is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_DisplayOrientation { @@ -137,7 +166,7 @@ typedef enum SDL_DisplayOrientation /** * The struct used as an opaque handle to a window. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateWindow */ @@ -151,7 +180,7 @@ typedef struct SDL_Window SDL_Window; * changed on existing windows by the app, and some of it might be altered by * the user or system outside of the app's control. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ @@ -185,31 +214,91 @@ typedef Uint64 SDL_WindowFlags; /** - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. * - * \since This macro is available since SDL 3.0.0. + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u + +/** + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) + +/** + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A magic value used with SDL_WINDOWPOS_CENTERED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u /** * Used to indicate that the window position should be centered. * - * \since This macro is available since SDL 3.0.0. + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. */ -#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) + +/** + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlashOperation { @@ -221,30 +310,102 @@ typedef enum SDL_FlashOperation /** * An opaque handle to an OpenGL context. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef int SDL_EGLint; /** - * EGL attribute initialization callback types. + * EGL platform attribute initialization callback. * - * \since This datatype is available since SDL 3.0.0. + * This is called when SDL is attempting to create an EGL context, to let the + * app add extra attributes to its eglGetPlatformDisplay() call. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks */ -typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); -typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); /** * An enumeration of OpenGL configuration attributes. @@ -261,9 +422,9 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); * fail if the GL can't provide your requested attributes at a minimum, but * you should check to see exactly what you got. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ -typedef enum SDL_GLattr +typedef enum SDL_GLAttr { SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ @@ -284,64 +445,64 @@ typedef enum SDL_GLattr SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ - SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ - SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLcontextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS, SDL_GL_EGL_PLATFORM -} SDL_GLattr; +} SDL_GLAttr; /** * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLprofile -{ - SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, - SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, - SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ -} SDL_GLprofile; +typedef Uint32 SDL_GLProfile; + +#define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */ +#define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */ +#define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ + /** - * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextFlag -{ - SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, - SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, - SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG = 0x0004, - SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 -} SDL_GLcontextFlag; +typedef Uint32 SDL_GLContextFlag; + +#define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001 +#define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002 +#define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004 +#define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008 + /** * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR * attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextReleaseFlag -{ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 -} SDL_GLcontextReleaseFlag; +typedef Uint32 SDL_GLContextReleaseFlag; + +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000 +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001 + /** * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLContextResetNotification -{ - SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, - SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 -} SDL_GLContextResetNotification; +typedef Uint32 SDL_GLContextResetNotification; + +#define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000 +#define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001 + /* Function prototypes */ @@ -350,7 +511,9 @@ typedef enum SDL_GLContextResetNotification * * \returns the number of built in video drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVideoDriver */ @@ -369,7 +532,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers */ @@ -385,7 +550,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); * \returns the name of the current video driver or NULL if no driver has been * initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers * \sa SDL_GetVideoDriver @@ -397,7 +564,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); * * \returns the current system theme, light, dark, or unknown. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); @@ -410,7 +579,9 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); @@ -420,7 +591,9 @@ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); * \returns the instance ID of the primary display on success or 0 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -448,7 +621,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); @@ -462,7 +637,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa * \returns the name of a display or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -471,19 +648,22 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa /** * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the usable desktop area represented by a display, in screen @@ -499,15 +679,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayI * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the orientation of a display when it is unrotated. @@ -516,7 +698,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID di * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -529,7 +713,9 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -543,12 +729,21 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays */ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID); @@ -573,7 +768,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -587,7 +784,7 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * refresh rate default to the desktop mode if they are set to 0. The modes * are scanned with size being first priority, format being second priority, * and finally checking the refresh rate. If all the available modes are too - * small, then NULL is returned. + * small, then false is returned. * * \param displayID the instance ID of the display to query. * \param w the width in pixels of the desired display mode. @@ -596,17 +793,19 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * for the desktop refresh rate. * \param include_high_density_modes boolean to include high density modes in * the search. - * \param mode a pointer filled in with the closest display mode equal to or - * larger than the desired mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closest a pointer filled in with the closest display mode equal to + * or larger than the desired mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes, SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest); /** * Get information about the desktop's display mode. @@ -620,7 +819,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Dis * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayMode * \sa SDL_GetDisplays @@ -639,7 +840,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDisplays @@ -653,7 +856,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SD * \returns the instance ID of the display containing the point or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -668,7 +873,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point * closest to the center of the rect on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -683,7 +890,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect * * on success or 0 on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -701,7 +910,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowDisplayScale */ @@ -725,7 +936,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window); * \returns the display scale, or 0.0f on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); @@ -743,24 +956,26 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * taken effect. * * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an - * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new - * mode dimensions. + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode + * dimensions. * * \param window the window to affect. * \param mode a pointer to the display mode to use, which can be NULL for * borderless fullscreen desktop mode, or one of the fullscreen * modes returned by SDL_GetFullscreenDisplayModes() to set an * exclusive fullscreen mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreen * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); /** * Query the display mode to use when a window is visible at fullscreen. @@ -769,7 +984,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *win * \returns a pointer to the exclusive fullscreen mode to use or NULL for * borderless fullscreen desktop mode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -785,7 +1002,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode( * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); @@ -797,7 +1016,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); @@ -811,7 +1032,9 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); @@ -870,7 +1093,7 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). * * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. * * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, * SDL_CreateWindow() will fail. @@ -890,8 +1113,11 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindowAndRenderer * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindowWithProperties * \sa SDL_DestroyWindow @@ -901,36 +1127,41 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int /** * Create a child popup window of the specified parent window. * - * 'flags' **must** contain exactly one of the following: - - * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any - * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu. - * The topmost popup menu will implicitly gain the keyboard focus. + * The flags parameter **must** contain at least one of the following: + * + * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any + * input events. + * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost + * popup menu will implicitly gain the keyboard focus. * * The following flags are not relevant to popup window creation and will be * ignored: * - * - 'SDL_WINDOW_MINIMIZED' - * - 'SDL_WINDOW_MAXIMIZED' - * - 'SDL_WINDOW_FULLSCREEN' - * - 'SDL_WINDOW_BORDERLESS' + * - `SDL_WINDOW_MINIMIZED` + * - `SDL_WINDOW_MAXIMIZED` + * - `SDL_WINDOW_FULLSCREEN` + * - `SDL_WINDOW_BORDERLESS` + * + * The following flags are incompatible with popup window creation and will + * cause it to fail: + * + * - `SDL_WINDOW_UTILITY` + * - `SDL_WINDOW_MODAL` * * The parent parameter **must** be non-null and a valid window. The parent of * a popup window can be either a regular, toplevel window, or another popup * window. * * Popup windows cannot be minimized, maximized, made fullscreen, raised, - * flash, be made a modal window, be the parent of a modal window, or grab the - * mouse and/or keyboard. Attempts to do so will fail. + * flash, be made a modal window, be the parent of a toplevel window, or grab + * the mouse and/or keyboard. Attempts to do so will fail. * * Popup windows implicitly do not have a border/decorations and do not appear * on the taskbar/dock or in lists of windows such as alt-tab menus. * - * If a parent window is hidden, any child popup windows will be recursively - * hidden as well. Child popup windows not explicitly hidden will be restored - * when the parent is shown. - * - * If the parent window is destroyed, any child popup windows will be - * recursively destroyed as well. + * If a parent window is hidden or destroyed, any child popup windows will be + * recursively hidden or destroyed as well. Child popup windows not explicitly + * hidden will be restored when the parent is shown. * * \param parent the parent of the window, must not be NULL. * \param offset_x the x position of the popup window relative to the origin @@ -944,7 +1175,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_CreateWindowWithProperties @@ -987,7 +1220,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used * with OpenGL rendering * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the - * parent of this window, required for windows with the "toolip", "menu", + * parent of this window, required for windows with the "tooltip", "menu", * and "modal" properties * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be * resizable @@ -1003,10 +1236,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * * These are additional supported properties on macOS: * @@ -1024,8 +1259,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * [README/wayland](README/wayland) for more information on using custom * surfaces. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the - * application wants an associated `wl_egl_window` object to be created, - * even if the window does not have the OpenGL property or flag set. + * application wants an associated `wl_egl_window` object to be created and + * attached to the window, even if the window does not have the OpenGL + * property or `SDL_WINDOW_OPENGL` flag set. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface * associated with the window, if you want to wrap an existing window. See * [README/wayland](README/wayland) for more information. @@ -1061,7 +1297,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateWindow @@ -1114,7 +1352,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFromID */ @@ -1130,7 +1370,9 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window); * \returns the window associated with `id` or NULL if it doesn't exist; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowID */ @@ -1143,7 +1385,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id); * \returns the parent of the window on success or NULL if the window has no * parent. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow */ @@ -1181,7 +1425,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)` * UIWindow associated with the window * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag - * assocated with metal views on the window + * associated with metal views on the window * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's * framebuffer object. It must be bound when rendering to the screen using * OpenGL. @@ -1206,6 +1450,11 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag * assocated with metal views on the window * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the + * associated overlay window. + * * On Vivante: * * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType @@ -1215,11 +1464,6 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with * the window * - * On UWP: - * - * - `SDL_PROP_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow - * associated with the window - * * On Windows: * * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window @@ -1237,6 +1481,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * the window * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window * associated with the window * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated @@ -1263,7 +1509,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); @@ -1283,15 +1531,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window #define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev" #define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window" #define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag" +#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id" #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" -#define SDL_PROP_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window" #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" #define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display" #define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface" +#define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport" #define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window" #define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface" #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel" @@ -1308,7 +1557,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window * \param window the window to query. * \returns a mask of the SDL_WindowFlags associated with `window`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_HideWindow @@ -1327,14 +1578,16 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * * \param window the window to change. * \param title the desired window title in UTF-8 format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowTitle */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); /** * Get the title of a window. @@ -1343,7 +1596,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, cons * \returns the title of the window in UTF-8 format or "" if there is no * title. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowTitle */ @@ -1364,23 +1619,24 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); * * \param window the window to change. * \param icon an SDL_Surface structure containing the icon for the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); /** * Request that the window's position be set. * - * If, at the time of this request, the window is in a fixed-size state such - * as maximized, this request may be deferred until the window returns to a - * resizable state. + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. * * This can be used to reposition fullscreen-desktop windows onto a different - * display, however, exclusive fullscreen windows are locked to a specific - * display and can only be repositioned programmatically via + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via * SDL_SetWindowFullscreenMode(). * * On some windowing systems this request is asynchronous and the new @@ -1401,15 +1657,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_S * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * `SDL_WINDOWPOS_UNDEFINED`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); /** * Get the position of a window. @@ -1425,24 +1683,25 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, i * NULL. * \param y a pointer filled in with the y position of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowPosition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); /** * Request that the size of a window's client area be set. * - * If, at the time of this request, the window in a fixed-size state, such as - * maximized or fullscreen, the request will be deferred until the window - * exits this state and becomes resizable again. + * If the window is in a fullscreen or maximized state, this request has no + * effect. * - * To change the fullscreen mode of a window, use - * SDL_SetWindowFullscreenMode() + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). * * On some windowing systems, this request is asynchronous and the new window * size may not have have been applied immediately upon the return of this @@ -1459,16 +1718,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, i * \param window the window to change. * \param w the width of the window, must be > 0. * \param h the height of the window, must be > 0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); /** * Get the size of a window's client area. @@ -1480,16 +1741,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w * \param window the window to query the width and height from. * \param w a pointer filled in with the width of the window, may be NULL. * \param h a pointer filled in with the height of the window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize * \sa SDL_GetWindowSizeInPixels * \sa SDL_SetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); /** * Get the safe area for this window. @@ -1497,19 +1760,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int * * Some devices have portions of the screen which are partially obscured or * not interactive, possibly due to on-screen controls, curved edges, camera * notches, TV overscan, etc. This function provides the area of the window - * which is safe to have interactible content. You should continue rendering + * which is safe to have interactable content. You should continue rendering * into the rest of the window, but it should not contain visually important * or interactible content. * * \param window the window to query. * \param rect a pointer filled in with the client area that is safe for * interactive content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); /** * Request that the aspect ratio of a window's client area be set. @@ -1540,15 +1805,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, S * limit. * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); /** * Get the size of a window's client area. @@ -1558,19 +1825,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window * window, may be NULL. * \param max_aspect a pointer filled in with the maximum aspect ratio of the * window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowAspectRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); /** * Get the size of a window's borders (decorations) around the client area. * - * Note: If this function fails (returns -1), the size values will be + * Note: If this function fails (returns false), the size values will be * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the * window in question was borderless. * @@ -1580,7 +1849,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * window has been presented and composited, so that the window system has a * chance to decorate the window and provide the border dimensions to SDL. * - * This function also returns -1 if getting the information is not supported. + * This function also returns false if getting the information is not + * supported. * * \param window the window to query the size values of the border * (decorations) from. @@ -1592,14 +1862,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; * NULL is permitted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); /** * Get the size of a window's client area, in pixels. @@ -1609,15 +1881,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window * NULL. * \param h a pointer to variable for storing the height in pixels, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); /** * Set the minimum size of a window's client area. @@ -1625,15 +1899,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *windo * \param window the window to change. * \param min_w the minimum width of the window, or 0 for no limit. * \param min_h the minimum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); /** * Get the minimum size of a window's client area. @@ -1643,15 +1919,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the minimum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); /** * Set the maximum size of a window's client area. @@ -1659,15 +1937,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window * \param window the window to change. * \param max_w the maximum width of the window, or 0 for no limit. * \param max_h the maximum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); /** * Get the maximum size of a window's client area. @@ -1677,15 +1957,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the maximum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); /** * Set the border state of a window. @@ -1697,15 +1979,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window * You can't change the border state of a fullscreen window. * * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bool bordered); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); /** * Set the user-resizable state of a window. @@ -1717,15 +2001,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, S * You can't change the resizable state of a fullscreen window. * * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_bool resizable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); /** * Set the window to always be above the others. @@ -1734,43 +2020,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, * will bring the window to the front and keep the window above the rest. * * \param window the window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param on_top true to set the window always on top, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL_bool on_top); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); /** * Show a window. * * \param window the window to show. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); /** * Hide a window. * * \param window the window to hide. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); /** * Request that a window be raised above other windows and gain the input @@ -1783,12 +2075,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); /** * Request that the window be made as large as possible. @@ -1811,22 +2105,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); * and Wayland window managers may vary. * * \param window the window to maximize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MinimizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); /** * Request that the window be minimized to an iconic representation. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window - * state may not have have been applied immediately upon the return of this + * state may not have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to * block until the changes have taken effect. * @@ -1835,21 +2134,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to minimize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); /** * Request that the size and position of a minimized or maximized window be * restored. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1860,16 +2164,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to restore. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_MinimizeWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); /** * Request that the window's fullscreen state be changed. @@ -1888,18 +2194,20 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); * is just a request, it can be denied by the windowing system. * * \param window the window to change. - * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed - * mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); /** * Block until any pending window state is finalized. @@ -1915,10 +2223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * * \param window the window for which to wait for the pending state to be * applied. - * \returns SDL_TRUE on success or SDL_FALSE if the operation timed out before - * the window was in the requested state. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSize * \sa SDL_SetWindowPosition @@ -1928,20 +2238,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * \sa SDL_RestoreWindow * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SyncWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); /** * Return whether the window has a surface associated with it. * * \param window the window to query. - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. + * \returns true if there is a surface associated with the window, or false + * otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); /** * Get the SDL surface associated with the window. @@ -1961,7 +2273,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyWindowSurface * \sa SDL_WindowHasSurface @@ -1985,14 +2299,16 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * * \param window the window. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) @@ -2003,14 +2319,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *windo * \param window the window to query. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetWindowSurfaceVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); /** * Copy the window surface to the screen. @@ -2021,15 +2339,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *windo * This function is equivalent to the SDL 1.2 API SDL_Flip(). * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); /** * Copy areas of the window surface to the screen. @@ -2048,29 +2368,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window) * \param rects an array of SDL_Rect structures representing areas of the * surface to copy, in pixels. * \param numrects the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); /** * Destroy the surface associated with the window. * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); /** * Set a window's keyboard grab mode. @@ -2092,16 +2416,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window * other window loses its grab in favor of the caller's window. * * \param window the window for which the keyboard grab mode should be set. - * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab keyboard, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); /** * Set a window's mouse grab mode. @@ -2109,47 +2435,60 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *windo * Mouse grab confines the mouse cursor to the window. * * \param window the window for which the mouse grab mode should be set. - * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab mouse, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * - * \sa SDL_GetWindowMouseGrab + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); /** * Get a window's keyboard grab mode. * * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \returns true if keyboard is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); /** * Get a window's mouse grab mode. * * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \returns true if mouse is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); /** * Get the window that currently has an input grab enabled. * * \returns the window if input is grabbed or NULL otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab @@ -2165,15 +2504,18 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \param window the window that will be associated with the barrier. * \param rect a rectangle area in window-relative coordinates. If NULL the * barrier for the specified window will be destroyed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); /** * Get the mouse confinement rectangle of a window. @@ -2182,9 +2524,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, * \returns a pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab */ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window); @@ -2194,18 +2540,20 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * * The parameter `opacity` will be clamped internally between 0.0f * (transparent) and 1.0f (opaque). * - * This function also returns -1 if setting the opacity isn't supported. + * This function also returns false if setting the opacity isn't supported. * * \param window the window which will be made transparent or opaque. * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowOpacity */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); /** * Get the opacity of a window. @@ -2217,43 +2565,81 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, fl * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowOpacity */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); /** - * Set the window as a modal to a parent window. + * Set the window as a child of a parent window. * - * If the window is already modal to an existing window, it will be reparented - * to the new owner. Setting the parent window to null unparents the modal - * window and removes modal status. + * If the window is already the child of an existing window, it will be + * reparented to the new owner. Setting the parent window to NULL unparents + * the window and removes child window status. * - * Setting a window as modal to a parent that is a descendent of the modal - * window results in undefined behavior. + * If a parent window is hidden or destroyed, the operation will be + * recursively applied to child windows. Child windows hidden with the parent + * that did not have their hidden status explicitly set will be restored when + * the parent is shown. * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModal() to cancel the modal status before + * attempting to change the parent. * - * \since This function is available since SDL 3.0.0. + * Popup windows cannot change parents and attempts to do so will fail. + * + * Setting a parent window that is currently the sibling or descendent of the + * child window results in undefined behavior. + * + * \param window the window that should become the child of a parent. + * \param parent the new parent window for the child window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowModal */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window, SDL_Window *parent_window); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); /** * Set whether the window may have input focus. * * \param window the window to set focusable state. - * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow - * input focus. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param focusable true to allow input focus, false to not allow input focus. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_bool focusable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); /** @@ -2272,17 +2658,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, * the client area. * \param y the y coordinate of the menu, relative to the origin (top-left) of * the client area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); /** * Possible return values from the SDL_HitTest callback. * - * \since This enum is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This enum is available since SDL 3.2.0. * * \sa SDL_HitTest */ @@ -2335,7 +2725,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * Specifying NULL for a callback disables hit-testing. Hit-testing is * disabled by default. * - * Platforms that don't support this functionality will return SDL_FALSE + * Platforms that don't support this functionality will return false * unconditionally, even if you're attempting to disable hit-testing. * * Your callback may fire at any time, and its firing does not indicate any @@ -2349,58 +2739,72 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \param window the window to set hit-testing on. * \param callback the function to call when doing a hit-test. * \param callback_data an app-defined void pointer passed to **callback**. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); /** * Set the shape of a transparent window. * * This sets the alpha channel of a transparent window and any fully * transparent areas are also transparent to mouse clicks. If you are using - * something besides the SDL render API, then you are responsible for setting - * the alpha channel of the window yourself. + * something besides the SDL render API, then you are responsible for drawing + * the alpha channel of the window to match the shape alpha channel to get + * consistent cross-platform results. * * The shape is copied inside this function, so you can free it afterwards. If * your shape surface changes, you should call SDL_SetWindowShape() again to - * update the window. + * update the window. This is an expensive operation, so should be done + * sparingly. * * The window must have been created with the SDL_WINDOW_TRANSPARENT flag. * * \param window the window. * \param shape the surface representing the shape of the window, or NULL to * remove any current shape. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); /** * Request a window to demand attention from the user. * * \param window the window to be flashed. * \param operation the operation to perform. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); /** * Destroy a window. * - * Any popups or modal windows owned by the window will be recursively - * destroyed as well. + * Any child windows owned by the window will be recursively destroyed as + * well. + * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. * * \param window the window to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindow @@ -2416,28 +2820,31 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. + * \returns true if the screensaver is enabled, false if it is disabled. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenSaverEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); /** * Allow the screen to be blanked by a screen saver. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); /** * Prevent the screen from being blanked by a screen saver. @@ -2448,15 +2855,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); * The screensaver is disabled by default, but this may by changed by * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); /** @@ -2476,15 +2885,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); * * \param path the platform dependent OpenGL library name, or NULL to open the * default OpenGL library. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); /** * Get an OpenGL function by name. @@ -2531,7 +2942,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); * \returns a pointer to the named OpenGL function. The returned pointer * should be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ExtensionSupported * \sa SDL_GL_LoadLibrary @@ -2550,7 +2963,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char * \returns a pointer to the named EGL function. The returned pointer should * be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EGL_GetCurrentDisplay */ @@ -2559,7 +2974,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha /** * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_LoadLibrary */ @@ -2580,16 +2997,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * every time you need to know. * * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * \returns true if the extension is supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** * Reset all previously set OpenGL context attributes to their default values. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute @@ -2604,34 +3025,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * SDL_GL_GetAttribute() to check the values after creating the OpenGL * context, since the values obtained can differ from the requested ones. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * set. * \param value the desired value for the attribute. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * get. * \param value a pointer filled in with the current value of `attr`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value); /** * Create an OpenGL context for an OpenGL window, and make it current. @@ -2648,7 +3073,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *v * \returns the OpenGL context associated with `window` or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_DestroyContext * \sa SDL_GL_MakeCurrent @@ -2662,14 +3089,16 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * * \param window the window to associate with the context. * \param context the OpenGL context to associate with the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); /** * Get the currently active OpenGL window. @@ -2677,7 +3106,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_ * \returns the currently active OpenGL window on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); @@ -2687,7 +3118,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); * \returns the currently active OpenGL context or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_MakeCurrent */ @@ -2699,7 +3132,9 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * \returns the currently active EGL display or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); @@ -2709,7 +3144,9 @@ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); * \returns the currently active EGL config or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); @@ -2720,7 +3157,9 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); * \returns the EGLSurface pointer associated with the window, or NULL on * failure. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); @@ -2728,27 +3167,25 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * Sets the callbacks for defining custom EGLAttrib arrays for EGL * initialization. * - * Each callback should return a pointer to an EGL attribute array terminated - * with EGL_NONE. Callbacks may return NULL pointers to signal an error, which - * will cause the SDL_CreateWindow process to fail gracefully. - * - * The arrays returned by each callback will be appended to the existing - * attribute arrays defined by SDL. + * Callbacks that aren't needed can be set to NULL. * * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. * * \param platformAttribCallback callback for attributes to pass to - * eglGetPlatformDisplay. + * eglGetPlatformDisplay. May be NULL. * \param surfaceAttribCallback callback for attributes to pass to - * eglCreateSurface. + * eglCreateSurface. May be NULL. * \param contextAttribCallback callback for attributes to pass to - * eglCreateContext. + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, - SDL_EGLIntArrayCallback surfaceAttribCallback, - SDL_EGLIntArrayCallback contextAttribCallback); + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); /** * Set the swap interval for the current OpenGL context. @@ -2758,7 +3195,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * the vertical retrace for a given frame, it swaps buffers immediately, which * might be less jarring for the user during occasional framerate drops. If an * application requests adaptive vsync and the system does not support it, - * this function will fail and return SDL_FALSE. In such a case, you should + * this function will fail and return false. In such a case, you should * probably retry the call with 1 for the interval. * * Adaptive vsync is implemented for some glX drivers with @@ -2770,14 +3207,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * * \param interval 0 for immediate updates, 1 for updates synchronized with * the vertical retrace, -1 for adaptive vsync. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); /** * Get the swap interval for the current OpenGL context. @@ -2789,14 +3228,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); * synchronization, 1 if the buffer swap is synchronized with * the vertical retrace, and -1 if late swaps happen * immediately instead of waiting for the next retrace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_SetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); /** * Update a window with OpenGL rendering. @@ -2809,25 +3250,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); * extra. * * \param window the window to change. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); /** * Delete an OpenGL context. * * \param context the OpenGL context to be deleted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); /* @} *//* OpenGL support functions */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_vulkan.h b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_vulkan.h index c31d33c..5a48756 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_vulkan.h +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Headers/SDL_vulkan.h @@ -23,11 +23,25 @@ * # CategoryVulkan * * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. */ #ifndef SDL_vulkan_h_ #define SDL_vulkan_h_ +#include #include #include @@ -55,6 +69,10 @@ VK_DEFINE_HANDLE(VkPhysicalDevice) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) struct VkAllocationCallbacks; +/* Make sure to undef to avoid issues in case of later vulkan include */ +#undef VK_DEFINE_HANDLE +#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE + #endif /* !NO_SDL_VULKAN_TYPEDEFS */ /** @@ -69,6 +87,13 @@ struct VkAllocationCallbacks; * creating any Vulkan windows. If no Vulkan loader library is loaded, the * default library will be loaded upon creation of the first Vulkan window. * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * * It is fairly common for Vulkan applications to link with libvulkan instead * of explicitly loading it at run time. This will work with SDL provided the * application links to a dynamic library and both it and SDL use the same @@ -95,15 +120,17 @@ struct VkAllocationCallbacks; * library version. * * \param path the platform dependent Vulkan loader library name or NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); /** * Get the address of the `vkGetInstanceProcAddr` function. @@ -122,14 +149,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); /** * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_LoadLibrary */ @@ -153,7 +193,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * \returns an array of extension name strings on success, NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_CreateSurface */ @@ -175,15 +215,15 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension * allocator that creates the surface. Can be NULL. * \param surface a pointer to a VkSurfaceKHR handle to output the newly * created surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_DestroySurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, const struct VkAllocationCallbacks *allocator, VkSurfaceKHR* surface); @@ -206,7 +246,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window * \param allocator a VkAllocationCallbacks struct, which lets the app set the * allocator that destroys the surface. Can be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_CreateSurface @@ -226,14 +266,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, * \param physicalDevice a valid Vulkan physical device handle. * \param queueFamilyIndex a valid queue family index for the given physical * device. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error - * occurred. + * \returns true if supported, false if unsupported or an error occurred. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/INSTALL.md b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/INSTALL.md new file mode 100644 index 0000000..97e4ab6 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/INSTALL.md @@ -0,0 +1,41 @@ + +# Using this package + +This package contains SDL built for Xcode. + +To use this package in Xcode, drag `SDL3.framework` into your project. + +# Documentation + +An API reference, tutorials, and additional documentation is available at: + +https://wiki.libsdl.org/SDL3 + +# Example code + +There are simple example programs available at: + +https://examples.libsdl.org/SDL3 + +# Discussions + +## Discord + +You can join the official Discord server at: + +https://discord.com/invite/BwpFGBWsv8 + +## Forums/mailing lists + +You can join SDL development discussions at: + +https://discourse.libsdl.org/ + +Once you sign up, you can use the forum through the website or as a mailing list from your email client. + +## Announcement list + +You can sign up for the low traffic announcement list at: + +https://www.libsdl.org/mailing-list.php + diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Info.plist b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Info.plist index 0555f88..c0a15f5 100644 Binary files a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Info.plist and b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/Info.plist differ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/License.txt b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/License.txt index 42f3736..23abb73 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/License.txt +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/License.txt @@ -1,6 +1,4 @@ - -Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -17,3 +15,4 @@ freely, subject to the following restrictions: 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. + diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/README.md b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/README.md new file mode 100644 index 0000000..68b0923 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/README.md @@ -0,0 +1,17 @@ + +Simple DirectMedia Layer (SDL for short) is a cross-platform library +designed to make it easy to write multi-media software, such as games +and emulators. + +You can find the latest release and additional information at: +https://www.libsdl.org/ + +Installation instructions and a quick introduction is available in +[INSTALL.md](INSTALL.md) + +This library is distributed under the terms of the zlib license, +available in [LICENSE.txt](LICENSE.txt). + +Enjoy! + +Sam Lantinga (slouken@libsdl.org) diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/ReadMe.txt b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/ReadMe.txt deleted file mode 100644 index 6ea9347..0000000 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/ReadMe.txt +++ /dev/null @@ -1,44 +0,0 @@ -The Simple DirectMedia Layer (SDL for short) is a cross-platform -library designed to make it easy to write multi-media software, -such as games and emulators. - -The Simple DirectMedia Layer library source code is available from: -http://www.libsdl.org/ - -This library is distributed under the terms of the zlib license: -http://zlib.net/zlib_license.html - - -This packages contains the SDL framework for macOS. -Conforming with Apple guidelines, this framework -contains both the SDL runtime component and development header files. - - -To Install: -Copy "SDL3.xcframework" and "share" to /Library/Frameworks - -You may alternatively install it in /Library/Frameworks -if your access privileges are not high enough. - - -Use in CMake projects: -SDL3.xcframework can be used in CMake projects using the following pattern: -```cmake -find_package(SDL3 REQUIRED COMPONENTS SDL3) -add_executable(my_game ${MY_SOURCES}) -target_link_libraries(my_game PRIVATE SDL3::SDL3) -``` -If SDL3.framework is installed in a non-standard location, -please refer to the following link for ways to configure CMake: -https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure - - -Additional References: - - - Screencast tutorials for getting started with OpenSceneGraph/macOS are - available at: - http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips - Though these are OpenSceneGraph centric, the same exact concepts apply to - SDL, thus the videos are recommended for everybody getting started with - developing on macOS. (You can skim over the PlugIns stuff since SDL - doesn't have any PlugIns to worry about.) diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/SDL3 b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/SDL3 index b115290..0804853 100755 Binary files a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/SDL3 and b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/SDL3 differ diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/compile_shaders.sh b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/compile_shaders.sh deleted file mode 100755 index ef5e744..0000000 --- a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/compile_shaders.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/bin/bash - -set -x -set -e -cd `dirname "$0"` - -shadernames=(FullscreenVert BlitFrom2D BlitFrom2DArray BlitFrom3D BlitFromCube) - -generate_shaders() -{ - fileplatform=$1 - compileplatform=$2 - sdkplatform=$3 - minversion=$4 - - for shadername in "${shadernames[@]}"; do - xcrun -sdk $sdkplatform metal -c -std=$compileplatform-metal1.1 -m$sdkplatform-version-min=$minversion -Wall -O3 -D COMPILE_$shadername -o ./$shadername.air ./Metal_Blit.metal || exit $? - xcrun -sdk $sdkplatform metallib -o $shadername.metallib $shadername.air || exit $? - xxd -i $shadername.metallib | perl -w -p -e 's/\Aunsigned /const unsigned /;' >./${shadername}_$fileplatform.h - rm -f $shadername.air $shadername.metallib - done -} - -generate_shaders macos macos macosx 10.11 -generate_shaders ios ios iphoneos 8.0 -generate_shaders iphonesimulator ios iphonesimulator 8.0 -generate_shaders tvos ios appletvos 9.0 -generate_shaders tvsimulator ios appletvsimulator 9.0 - -# Bundle together one mega-header -catShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - cat ${shadername}_$target.h >> Metal_Blit.h - done -} - -rm -f Metal_Blit.h -echo "#if defined(SDL_PLATFORM_IOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders iphonesimulator - echo "#else" >> Metal_Blit.h - catShaders ios - echo "#endif" >> Metal_Blit.h -echo "#elif defined(SDL_PLATFORM_TVOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders tvsimulator - echo "#else" >> Metal_Blit.h - catShaders tvos - echo "#endif" >> Metal_Blit.h -echo "#else" >> Metal_Blit.h - catShaders macos -echo "#endif" >> Metal_Blit.h - -# Clean up -cleanupShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - rm -f ${shadername}_$target.h - done -} -cleanupShaders iphonesimulator -cleanupShaders ios -cleanupShaders tvsimulator -cleanupShaders tvos -cleanupShaders macos \ No newline at end of file diff --git a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/default.metallib b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/default.metallib index 24685fd..117cef8 100644 Binary files a/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/default.metallib and b/Frameworks/SDL3.xcframework/ios-arm64/SDL3.framework/default.metallib differ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/sdl3-config.cmake b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3Config.cmake similarity index 98% rename from Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/sdl3-config.cmake rename to Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3Config.cmake index 784d27d..03673f3 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/sdl3-config.cmake +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3Config.cmake @@ -59,7 +59,7 @@ if(NOT TARGET SDL3::SDL3-shared) set_target_properties(SDL3::SDL3-shared PROPERTIES FRAMEWORK "TRUE" - IMPORTED_LOCATION "${_sdl3_framework_path}/SDL3" + IMPORTED_LOCATION "${_sdl3_framework_path}" INTERFACE_LINK_LIBRARIES "SDL3::Headers" COMPATIBLE_INTERFACE_BOOL "SDL3_SHARED" INTERFACE_SDL3_SHARED "ON" diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config-version.cmake b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3ConfigVersion.cmake similarity index 100% rename from Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config-version.cmake rename to Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3ConfigVersion.cmake diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h index c963394..861c404 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -20,9 +20,12 @@ */ /** - * \file SDL.h + * Main include header for the SDL library, version 3.2.0 * - * Main include header for the SDL library, version 3.1.2 + * It is almost always best to include just this one header instead of + * picking out individual headers included here. There are exceptions to + * this rule--SDL_main.h is special and not included here--but usually + * letting SDL.h include the kitchen sink for you is the correct approach. */ #ifndef SDL_h_ @@ -30,6 +33,7 @@ #include #include +#include #include #include #include @@ -65,6 +69,7 @@ #include #include #include +#include #include #include #include @@ -76,6 +81,7 @@ #include #include #include +#include #include #include #include diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h index f5f798e..09b3b47 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,9 +51,14 @@ * - It provides statistics and data on all failed assertions to the app. * - It allows the default assertion handler to be controlled with environment * variables, in case an automated script needs to control it. + * - It can be used as an aid to Clang's static analysis; it will treat SDL + * assertions as universally true (under the assumption that you are serious + * about the asserted claims and that your debug builds will detect when + * these claims were wrong). This can help the analyzer avoid false + * positives. * - * To use it: do a debug build and just sprinkle around tests to check your - * code! + * To use it: compile a debug build and just sprinkle around tests to check + * your code! */ #ifndef SDL_assert_h_ @@ -84,7 +89,7 @@ extern "C" { * - 3: Paranoid settings: All SDL assertion macros enabled, including * SDL_assert_paranoid. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors @@ -113,24 +118,27 @@ extern "C" { * * If the program is not running under a debugger, SDL_TriggerBreakpoint will * likely terminate the app, possibly without warning. If the current platform - * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro - * does nothing. + * isn't supported, this macro is left undefined. * - * \threadsafety It is safe to call this function from any thread. + * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner -#elif defined(_MSC_VER) +#elif 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) #include #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__)) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) @@ -147,18 +155,40 @@ extern "C" { #include #define SDL_TriggerBreakpoint() raise(SIGTRAP) #else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ #endif -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FUNCTION __FUNCTION__ + +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ # define SDL_FUNCTION __func__ #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) # define SDL_FUNCTION __FUNCTION__ #else # define SDL_FUNCTION "???" #endif + +/** + * A macro that reports the current file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FILE __FILE__ + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_LINE __LINE__ /* @@ -176,14 +206,50 @@ This also solves the problem of... disable assertions. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro for wrapping code in `do {} while (0);` without compiler warnings. + * + * Visual Studio with really aggressive warnings enabled needs this to avoid + * compiler complaints. + * + * the `do {} while (0);` trick is useful for wrapping code in a macro that + * may or may not be a single statement, to avoid various C language + * accidents. + * + * To use: + * + * ```c + * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0)); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NULL_WHILE_LOOP_CONDITION (0) + +#elif defined(_MSC_VER) /* Avoid /W4 warnings. */ /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking this condition isn't constant. And looks like an owl's face! */ -#ifdef _MSC_VER /* stupid /W4 warnings. */ #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) #else #define SDL_NULL_WHILE_LOOP_CONDITION (0) #endif +/** + * The macro used when an assertion is disabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is disabled (perhaps in a release build). + * + * The code does nothing, but wraps `condition` in a sizeof operator, which + * generates no code and has no side effects, but avoid compiler warnings + * about unused variables. + * + * \param condition the condition to assert (but not actually run here). + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -198,7 +264,7 @@ disable assertions. * condition, try to break in a debugger, kill the program, or ignore the * problem). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AssertState { @@ -216,11 +282,11 @@ typedef enum SDL_AssertState * used by the assertion handler, then added to the assertion report. This is * returned as a linked list from SDL_GetAssertionReport(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AssertData { - SDL_bool always_ignore; /**< SDL_TRUE if app should always continue when assertion is triggered. */ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ const char *condition; /**< A string of this assert's test code. */ const char *filename; /**< The source file where this assert lives. */ @@ -232,7 +298,7 @@ typedef struct SDL_AssertData /** * Never call this directly. * - * Use the SDL_assert* macros instead. + * Use the SDL_assert macros instead. * * \param data assert data structure. * \param func function name. @@ -240,29 +306,57 @@ typedef struct SDL_AssertData * \param line line number. * \returns assert state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN; -/* Define the trigger breakpoint call used in asserts */ -#ifndef SDL_AssertBreakpoint -#if defined(ANDROID) && defined(assert) -/* Define this as empty in case assert() is defined as SDL_assert */ -#define SDL_AssertBreakpoint() -#else + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The macro used when an assertion triggers a breakpoint. + * + * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint + * instead. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() -#endif + +#elif !defined(SDL_AssertBreakpoint) +# if defined(ANDROID) && defined(assert) + /* Define this as empty in case assert() is defined as SDL_assert */ +# define SDL_AssertBreakpoint() +# else +# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() +# endif #endif /* !SDL_AssertBreakpoint */ -/* the do {} while(0) avoids dangling else problems: - if (x) SDL_assert(y); else blah(); - ... without the do/while, the "else" could attach to this macro's "if". - We try to handle just the minimum we need here in a macro...the loop, - the static vars, and break points. The heavy lifting is handled in - SDL_ReportAssertion(), in SDL_assert.c. -*/ +/** + * The macro used when an assertion is enabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is enabled. + * + * The `do {} while(0)` avoids dangling else problems: + * + * ```c + * if (x) SDL_assert(y); else blah(); + * ``` + * + * ... without the do/while, the "else" could attach to this macro's "if". We + * try to handle just the minimum we need here in a macro...the loop, the + * static vars, and break points. The heavy lifting is handled in + * SDL_ReportAssertion(). + * + * \param condition the condition to assert. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ @@ -305,7 +399,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; } @@ -336,7 +432,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_release(condition) SDL_disabled_assert(condition) @@ -363,7 +461,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) @@ -389,7 +489,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * #endif /** - * An assertion test that always performed. + * An assertion test that is always performed. * * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You * almost never want to use this, as it could trigger on an end-user's system, @@ -405,7 +505,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_always(condition) SDL_enabled_assert(condition) @@ -418,7 +520,10 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. * - * \since This datatype is available since SDL 3.0.0. + * \threadsafety This callback may be called from any thread that triggers an + * assert at any time. + * + * \since This datatype is available since SDL 3.2.0. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( const SDL_AssertData *data, void *userdata); @@ -440,7 +545,9 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * fails or NULL for the default handler. * \param userdata a pointer that is passed to `handler`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -459,7 +566,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler( * \returns the default SDL_AssertionHandler that is called when an assert * triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -482,7 +591,9 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler( * was passed to SDL_SetAssertionHandler(). * \returns the SDL_AssertionHandler that is called when an assert triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAssertionHandler */ @@ -508,9 +619,15 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void ** * ``` * * \returns a list of all failed assertions or NULL if the list is empty. This - * memory should not be modified or freed by the application. + * memory should not be modified or freed by the application. This + * pointer remains valid until the next call to SDL_Quit() or + * SDL_ResetAssertionReport(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads calling + * SDL_ResetAssertionReport() simultaneously, may render the + * returned pointer invalid. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetAssertionReport */ @@ -524,7 +641,11 @@ extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); * no items. In addition, any previously-triggered assertions will be reset to * a trigger_count of zero, and their always_ignore state will be false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads triggering an + * assertion, or simultaneously calling this function may cause + * memory leaks or crashes. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionReport */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_asyncio.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_asyncio.h new file mode 100644 index 0000000..b36cb07 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/* WIKI CATEGORY: AsyncIO */ + +/** + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + */ + +#ifndef SDL_asyncio_h_ +#define SDL_asyncio_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOTaskType +{ + SDL_ASYNCIO_TASK_READ, /**< A read operation. */ + SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */ + SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */ +} SDL_AsyncIOTaskType; + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOResult +{ + SDL_ASYNCIO_COMPLETE, /**< request was completed without error */ + SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */ + SDL_ASYNCIO_CANCELED /**< request was canceled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AsyncIOOutcome +{ + SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + void *buffer; /**< buffer where data was read/written. */ + Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + void *userdata; /**< pointer provided by the app when starting the task */ +} SDL_AsyncIOOutcome; + +/** + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode); + +/** + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); + +/** + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); + +/** + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome); + +/** + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS); + +/** + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_asyncio_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h index f159bcd..03e3fb1 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -88,15 +88,16 @@ typedef int SDL_SpinLock; * doing. Please be careful using any sort of spinlock!*** * * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. + * \returns true if the lock succeeded, false if the lock is already held. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_UnlockSpinlock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); /** * Lock a spin lock by setting it to a non-zero value. @@ -106,7 +107,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockSpinlock * \sa SDL_UnlockSpinlock @@ -123,7 +126,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_TryLockSpinlock @@ -147,9 +152,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -166,7 +172,50 @@ extern __inline void SDL_CompilerBarrier(void); #endif /** - * Insert a memory release barrier. + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); + +/** + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Insert a memory release barrier (macro version). * * Memory barriers are designed to prevent reads and writes from being * reordered by the compiler and being seen out of order on multi-core CPUs. @@ -186,31 +235,47 @@ extern __inline void SDL_CompilerBarrier(void); * For more information on these semantics, take a look at the blog post: * http://preshing.com/20120913/acquire-and-release-semantics * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierReleaseFunction to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() /** - * Insert a memory acquire barrier. + * Insert a memory acquire barrier (macro version). * - * Please refer to SDL_MemoryBarrierReleaseFunction for the details! + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. * - * \threadsafety Obviously this function is safe to use from any thread at any + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_MemoryBarrierReleaseFunction + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -/* !!! FIXME: this should have documentation! */ -#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) +#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") #elif defined(__GNUC__) && defined(__aarch64__) @@ -225,8 +290,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); hard-coded at address 0xffff0fa0 */ typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() #else #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") @@ -276,9 +341,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * * \threadsafety This macro is safe to use from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay + #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */ #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__) @@ -303,9 +369,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * A type representing an atomic integer value. * * This can be used to manage a value that is synchronized across multiple - * CPUs without a race condition; when an app sets a value with SDL_AtomicSet - * all other threads, regardless of the CPU it is running on, will see that - * value when retrieved with SDL_AtomicGet, regardless of CPU caches, etc. + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. * * This is also useful for atomic compare-and-swap operations: a thread can * change the value as long as its current value matches expectations. When @@ -316,14 +383,14 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * this!). * * This is a struct so people don't accidentally use numeric operations on it - * directly. You have to use SDL_Atomic* functions. + * directly. You have to use SDL atomic functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - * \sa SDL_AtomicAdd + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt */ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; @@ -336,15 +403,16 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; * \param a a pointer to an SDL_AtomicInt variable to be modified. * \param oldval the old value. * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. + * \returns true if the atomic variable was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, int oldval, int newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); /** * Set an atomic variable to a value. @@ -360,11 +428,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicGet + * \sa SDL_GetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); /** * Get the value of an atomic variable. @@ -377,11 +445,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicSet + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); /** * Add to an atomic variable. @@ -397,12 +465,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef * \sa SDL_AtomicIncRef */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); #ifndef SDL_AtomicIncRef @@ -414,11 +482,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to an SDL_AtomicInt to increment. * \returns the previous value of the atomic variable. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef */ -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) #endif #ifndef SDL_AtomicDecRef @@ -429,16 +499,103 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * ***Note: If you don't know what this macro is for, you shouldn't use it!*** * * \param a a pointer to an SDL_AtomicInt to increment. - * \returns SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise. + * \returns true if the variable reached zero after decrementing, false + * otherwise. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicIncRef */ -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) #endif +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***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 oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * 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. + * \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.2.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***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. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + /** * Set a pointer to a new value if it is currently an old value. * @@ -448,17 +605,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to a pointer. * \param oldval the old pointer value. * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. + * \returns true if the pointer was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGetPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, void *oldval, void *newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); /** * Set a pointer to a value atomically. @@ -472,12 +629,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicGetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); /** * Get the value of a pointer atomically. @@ -490,12 +647,12 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicGetPointer(void **a); +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h index b7a4b7b..9569382 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -33,8 +33,9 @@ * even if the data format changes on either side halfway through. * * An app opens an audio device and binds any number of audio streams to it, - * feeding more data to it as available. When the devices needs more data, it - * will pull it from all bound streams and mix them together for playback. + * feeding more data to the streams as available. When the device needs more + * data, it will pull it from all bound streams and mix them together for + * playback. * * Audio streams can also use an app-provided callback to supply data * on-demand, which maps pretty closely to the SDL2 audio model. @@ -43,6 +44,45 @@ * if you aren't reading from a file) as a basic means to load sound data into * your program. * + * ## Logical audio devices + * + * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a + * logical device ID that you can bind audio streams to. In almost all cases, + * logical devices can be used anywhere in the API that a physical device is + * normally used. However, since each device opening generates a new logical + * device, different parts of the program (say, a VoIP library, or + * text-to-speech framework, or maybe some other sort of mixer on top of SDL) + * can have their own device opens that do not interfere with each other; each + * logical device will mix its separate audio down to a single buffer, fed to + * the physical device, behind the scenes. As many logical devices as you like + * can come and go; SDL will only have to open the physical device at the OS + * level once, and will manage all the logical devices on top of it + * internally. + * + * One other benefit of logical devices: if you don't open a specific physical + * device, instead opting for the default, SDL can automatically migrate those + * logical devices to different hardware as circumstances change: a user + * plugged in headphones? The system default changed? SDL can transparently + * migrate the logical devices to the correct physical device seamlessly and + * keep playing; the app doesn't even have to know it happened if it doesn't + * want to. + * + * ## Simplified audio + * + * As a simplified model for when a single source of audio is all that's + * needed, an app can use SDL_OpenAudioDeviceStream, which is a single + * function to open an audio device, create an audio stream, bind that stream + * to the newly-opened device, and (optionally) provide a callback for + * obtaining audio data. When using this function, the primary interface is + * the SDL_AudioStream and the device handle is mostly hidden away; destroying + * a stream created through this function will also close the device, stream + * bindings cannot be changed, etc. One other quirk of this is that the device + * is started in a _paused_ state and must be explicitly resumed; this is + * partially to offer a clean migration for SDL2 apps and partially because + * the app might have to do more setup before playback begins; in the + * non-simplified form, nothing will play until a stream is bound to a device, + * so they start _unpaused_. + * * ## Channel layouts * * Audio data passing through SDL is uncompressed PCM data, interleaved. One @@ -73,7 +113,7 @@ * - 4 channels (quad) layout: FL, FR, BL, BR * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be - * BL, BR) + * SL, SR) * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR * @@ -94,7 +134,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -102,19 +141,73 @@ extern "C" { #endif -/* masks for different parts of SDL_AudioFormat. */ +/** + * Mask of bits in an SDL_AudioFormat that contains the format bit size. + * + * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BITSIZE (0xFFu) + +/** + * Mask of bits in an SDL_AudioFormat that contain the floating point flag. + * + * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_FLOAT (1u<<8) + +/** + * Mask of bits in an SDL_AudioFormat that contain the bigendian flag. + * + * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN + * instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12) + +/** + * Mask of bits in an SDL_AudioFormat that contain the signed data flag. + * + * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_SIGNED (1u<<15) -#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \ - (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) +/** + * Define an SDL_AudioFormat value. + * + * SDL does not support custom audio formats, so this macro is not of much use + * externally, but it can be illustrative as to what the various bits of an + * SDL_AudioFormat mean. + * + * For example, SDL_AUDIO_S32LE looks like this: + * + * ```c + * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32) + * ``` + * + * \param signed 1 for signed data, 0 for unsigned data. + * \param bigendian 1 for bigendian data, 0 for littleendian data. + * \param flt 1 for floating point data, 0 for integer data. + * \param size number of bits per sample. + * \returns a format value in the style of SDL_AudioFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \ + (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) /** * Audio format. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_AUDIO_BITSIZE * \sa SDL_AUDIO_BYTESIZE @@ -144,17 +237,18 @@ typedef enum SDL_AudioFormat /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ -} SDL_AudioFormat; -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_AUDIO_S16 SDL_AUDIO_S16LE -#define SDL_AUDIO_S32 SDL_AUDIO_S32LE -#define SDL_AUDIO_F32 SDL_AUDIO_F32LE -#else -#define SDL_AUDIO_S16 SDL_AUDIO_S16BE -#define SDL_AUDIO_S32 SDL_AUDIO_S32BE -#define SDL_AUDIO_F32 SDL_AUDIO_F32BE -#endif + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; /** @@ -167,7 +261,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) @@ -181,7 +275,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) @@ -195,7 +289,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) @@ -209,7 +303,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) @@ -223,7 +317,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) @@ -237,7 +331,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) @@ -251,7 +345,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) @@ -265,7 +359,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) @@ -275,7 +369,7 @@ typedef enum SDL_AudioFormat * * Zero is used to signify an invalid/null device. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_AudioDeviceID; @@ -286,7 +380,7 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu) @@ -297,14 +391,14 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu) /** * Format specifier for audio data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AudioFormat */ @@ -326,7 +420,7 @@ typedef struct SDL_AudioSpec * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) @@ -350,7 +444,7 @@ typedef struct SDL_AudioSpec * more of them, bind them to an opened audio device, and feed data to them * (or for recording, consume data from them). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -359,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream; /* Function prototypes */ -/** - * \name Driver discovery functions - * - * These functions return the list of built in audio drivers, in the - * order that they are normally initialized by default. - */ -/* @{ */ - /** * Use this function to get the number of built-in audio drivers. * @@ -384,7 +470,7 @@ typedef struct SDL_AudioStream SDL_AudioStream; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDriver */ @@ -408,12 +494,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. @@ -427,7 +512,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); @@ -453,7 +538,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioRecordingDevices @@ -482,7 +567,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioPlaybackDevices @@ -498,11 +583,10 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioPlaybackDevices * \sa SDL_GetAudioRecordingDevices - * \sa SDL_GetDefaultAudioInfo */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); @@ -532,14 +616,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI * \param spec on return, will be filled with device details. * \param sample_frames pointer to store device buffer size, in sample frames. * Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); /** * Get the current channel map of an audio device. @@ -558,7 +642,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -633,13 +717,52 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseAudioDevice * \sa SDL_GetAudioDeviceFormat */ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec); +/** + * Determine if an audio device is physical (instead of logical). + * + * An SDL_AudioDeviceID that represents physical hardware is a physical + * device; there is one for each piece of hardware that SDL can see. Logical + * devices are created by calling SDL_OpenAudioDevice or + * SDL_OpenAudioDeviceStream, and while each is associated with a physical + * device, there can be any number of logical devices on one physical device. + * + * For the most part, logical and physical IDs are interchangeable--if you try + * to open a logical device, SDL understands to assign that effort to the + * underlying physical device, etc. However, it might be useful to know if an + * arbitrary device ID is physical or logical. This function reports which. + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a physical device, false if it is logical. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid); + +/** + * Determine if an audio device is a playback device (instead of recording). + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a playback device, false if it is recording. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid); + /** * Use this function to pause audio playback on a specified device. * @@ -659,17 +782,17 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioDevice * \sa SDL_AudioDevicePaused */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to unpause audio playback on a specified device. @@ -687,17 +810,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev) * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AudioDevicePaused * \sa SDL_PauseAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to query if an audio device is paused. @@ -710,16 +833,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev * IDs will report themselves as unpaused here. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. + * \returns true if device is valid and paused, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Get the gain of an audio device. @@ -738,7 +861,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioDeviceGain */ @@ -753,8 +876,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * Audio devices default to a gain of 1.0f (no change in output). * * Physical devices may not have their gain changed, only logical devices, and - * this function will always return -1 when used on physical devices. While it - * might seem attractive to adjust several logical devices at once in this + * this function will always return false when used on physical devices. While + * it might seem attractive to adjust several logical devices at once in this * way, it would allow an app or library to interfere with another portion of * the program's otherwise-isolated devices. * @@ -767,17 +890,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \param devid the audio device on which to change gain. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDeviceGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); /** * Close a previously-opened audio device. @@ -794,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID de * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice */ @@ -819,23 +942,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * Binding a stream to a device will set its output format for playback * devices, and its input format for recording devices, so they match the * device's settings. The caller is welcome to change the other end of the - * stream's format at any time. + * stream's format at any time with SDL_SetAudioStreamFormat(). * * \param devid an audio device to bind a stream to. * \param streams an array of audio streams to bind. * \param num_streams number streams listed in the `streams` array. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams); /** * Bind a single audio stream to an audio device. @@ -845,18 +968,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devi * * \param devid an audio device to bind a stream to. * \param stream an audio stream to bind to a device. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); /** * Unbind a list of audio streams from their audio devices. @@ -867,16 +990,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid * * Unbinding a stream that isn't bound to a device is a legal no-op. * - * \param streams an array of audio streams to unbind. + * \param streams an array of audio streams to unbind. Can be NULL or contain + * NULL. * \param num_streams number streams listed in the `streams` array. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams */ -extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams); /** * Unbind a single audio stream from its audio device. @@ -884,11 +1008,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **stream * This is a convenience function, equivalent to calling * `SDL_UnbindAudioStreams(&stream, 1)`. * - * \param stream an audio stream to unbind from a device. + * \param stream an audio stream to unbind from a device. Can be NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream */ @@ -907,7 +1031,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream * \sa SDL_BindAudioStreams @@ -924,7 +1048,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_GetAudioStreamData @@ -943,7 +1067,9 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream); @@ -953,17 +1079,17 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * \param stream the SDL_AudioStream to query. * \param src_spec where to store the input audio format; ignored if NULL. * \param dst_spec where to store the output audio format; ignored if NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); /** * Change the input and output formats of an audio stream. @@ -978,23 +1104,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *s * next sound file, and start putting that new data while the previous sound * file is still queued, and everything will still play back correctly. * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * * \param stream the stream the format is being changed. * \param src_spec the new format of the audio input; if NULL, it is not * changed. * \param dst_spec the new format of the audio output; if NULL, it is not * changed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFormat * \sa SDL_SetAudioStreamFrequencyRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** * Get the frequency ratio of an audio stream. @@ -1006,7 +1138,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *s * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFrequencyRatio */ @@ -1027,18 +1159,18 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \param stream the stream the frequency ratio is being changed. * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 * and 100. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Get the gain of an audio stream. @@ -1055,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioS * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGain */ @@ -1074,17 +1206,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \param stream the stream on which the gain is being changed. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); /** * Get the current input channel map of an audio stream. @@ -1104,7 +1236,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *str * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1128,7 +1260,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStr * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1148,8 +1280,12 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * Data that was previously queued in the stream will still be operated on in * the order that was current when it was added, which is to say you can put @@ -1164,26 +1300,31 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Set the current output channel map of an audio stream. @@ -1194,12 +1335,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * The output channel map reorders data that leaving a stream via * SDL_GetAudioStreamData. * - * Each item in the array represents an output channel, and its value is the + * Each item in the array represents an input channel, and its value is the * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * The output channel map can be changed at any time, as output remapping is * applied during SDL_GetAudioStreamData. @@ -1211,26 +1356,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Add data to the stream. @@ -1246,21 +1398,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_Audi * \param stream the stream the audio data is being added to. * \param buf a pointer to the audio data to add. * \param len the number of bytes to write to the stream. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but if the * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_FlushAudioStream * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); /** * Get converted/resampled data from the stream. @@ -1284,7 +1436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *str * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_GetAudioStreamAvailable @@ -1311,7 +1463,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamData * \sa SDL_PutAudioStreamData @@ -1322,6 +1474,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str /** * Get the number of bytes currently queued. * + * This is the number of bytes put into a stream as input, not the number that + * can be retrieved as output. Because of several details, it's not possible + * to calculate one number directly from the other. If you need to know how + * much usable data can be retrieved right now, you should use + * SDL_GetAudioStreamAvailable() and not this function. + * * Note that audio streams can change their input format at any time, even if * there is still data queued in a different format, so the returned byte * count will not necessarily match the number of _sample frames_ available. @@ -1344,7 +1502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_ClearAudioStream @@ -1361,16 +1519,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * input, so the complete output becomes available. * * \param stream the audio stream to flush. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** * Clear any pending data in the stream. @@ -1379,19 +1537,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *strea * stream until more is added. * * \param stream the audio stream to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamAvailable * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); /** * Use this function to pause audio playback on the audio device associated @@ -1406,16 +1564,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *strea * loading, etc. * * \param stream the audio stream associated with the audio device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); /** * Use this function to unpause audio playback on the audio device associated @@ -1426,16 +1584,36 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream * to progress again, and audio can be generated. * * \param stream the audio stream associated with the audio device to resume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to query if an audio device associated with a stream is + * paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * \param stream the audio stream associated with the audio device to query. + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream); + /** * Lock an audio stream for serialized access. @@ -1454,16 +1632,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream * all the same attributes (recursive locks are allowed, etc). * * \param stream the audio stream to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); /** @@ -1472,17 +1650,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream * This unlocks an audio stream after a call to SDL_LockAudioStream. * * \param stream the audio stream to unlock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety You should only call this from the same thread that * previously called SDL_LockAudioStream. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); /** * A callback that fires when data passes through an SDL_AudioStream. @@ -1519,7 +1697,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stre * is called, so your callback does not need to manage the lock * explicitly. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback * \sa SDL_SetAudioStreamPutCallback @@ -1561,16 +1739,16 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * from the stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamPutCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** * Set a callback that runs when data is added to an audio stream. @@ -1610,16 +1788,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStre * stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** @@ -1637,7 +1815,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStre * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -1699,7 +1877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamDevice * \sa SDL_ResumeAudioStreamDevice @@ -1737,7 +1915,7 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_Audi * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioPostmixCallback */ @@ -1788,14 +1966,14 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio * \param devid the ID of an opened audio device. * \param callback a callback function to be called. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); /** @@ -1839,7 +2017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * Example: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); + * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len); * ``` * * Note that the SDL_LoadWAV function does this same thing for you, but in a @@ -1850,19 +2028,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * ``` * * \param src the data source for the WAVE data. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE * data's format details on successful return. * \param audio_buf a pointer filled with the audio data, allocated by the * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1871,12 +2049,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Loads a WAV from a file path. @@ -1884,7 +2062,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * This is a convenience function that is effectively the same as: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), SDL_TRUE, spec, audio_buf, audio_len); + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); * ``` * * \param path the file path of the WAV file to open. @@ -1894,11 +2072,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1907,12 +2085,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Mix audio data in a specified format. @@ -1941,14 +2119,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * \param len the length of the audio buffer in bytes. * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full * audio volume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); /** * Convert some audio data of one format to another format. @@ -1971,14 +2149,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, * which should be freed with SDL_free(). On error, it will be * NULL. * \param dst_len will be filled with the len of dst_data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); /** * Get the human readable name of an audio format. @@ -1989,7 +2167,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); @@ -2005,7 +2183,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h index f418c61..a6b47cf 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,15 @@ /* WIKI CATEGORY: BeginCode */ /** - * SDL_begin_code.h sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * # CategoryBeginCode + * + * `SDL_begin_code.h` sets things up for C dynamic library function + * definitions, static inlined functions, and structures aligned at 4-byte + * alignment. If you don't like ugly C preprocessor code, don't look at this + * file. :) + * + * SDL's headers use this; applications generally should not include this + * header directly. */ /* This shouldn't be nested -- included it around code only. */ @@ -33,6 +39,259 @@ #endif #define SDL_begin_code_h +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a symbol as deprecated. + * + * A function is marked deprecated by adding this macro to its declaration: + * + * ```c + * extern SDL_DEPRECATED int ThisFunctionWasABadIdea(void); + * ``` + * + * Compilers with deprecation support can give a warning when a deprecated + * function is used. This symbol may be used in SDL's headers, but apps are + * welcome to use it for their own interfaces as well. + * + * SDL, on occasion, might deprecate a function for various reasons. However, + * SDL never removes symbols before major versions, so deprecated interfaces + * in SDL3 will remain available until SDL4, where it would be expected an app + * would have to take steps to migrate anyhow. + * + * On compilers without a deprecation mechanism, this is defined to nothing, + * and using a deprecated function will not generate a warning. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEPRECATED __attribute__((deprecated)) + +/** + * A macro to tag a symbol as a public API. + * + * SDL uses this macro for all its public functions. On some targets, it is + * used to signal to the compiler that this function needs to be exported from + * a shared library, but it might have other side effects. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DECLSPEC __attribute__ ((visibility("default"))) + +/** + * A macro to set a function's calling conventions. + * + * SDL uses this macro for all its public functions, and any callbacks it + * defines. This macro guarantees that calling conventions match between SDL + * and the app, even if the two were built with different compilers or + * optimization settings. + * + * When writing a callback function, it is very important for it to be + * correctly tagged with SDLCALL, as mismatched calling conventions can cause + * strange behaviors and can be difficult to diagnose. Plus, on many + * platforms, SDLCALL is defined to nothing, so compilers won't be able to + * warn that the tag is missing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDLCALL __cdecl + +/** + * A macro to request a function be inlined. + * + * This is a hint to the compiler to inline a function. The compiler is free + * to ignore this request. On compilers without inline support, this is + * defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INLINE __inline + +/** + * A macro to demand a function be inlined. + * + * This is a command to the compiler to inline a function. SDL uses this macro + * in its public headers for a handful of simple functions. On compilers + * without forceinline support, this is defined to `static SDL_INLINE`, which + * is often good enough. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FORCE_INLINE __forceinline + +/** + * A macro to tag a function as never-returning. + * + * This is a hint to the compiler that a function does not return. An example + * of a function like this is the C runtime's exit() function. + * + * This hint can lead to code optimizations, and help analyzers understand + * code flow better. On compilers without noreturn support, this is defined to + * nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NORETURN __attribute__((noreturn)) + +/** + * A macro to tag a function as never-returning (for analysis purposes). + * + * This is almost identical to SDL_NORETURN, except functions marked with this + * _can_ actually return. The difference is that this isn't used for code + * generation, but rather static analyzers use this information to assume + * truths about program state and available code paths. Specifically, this tag + * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this + * tag behind the scenes. Generally, apps that don't understand the specific + * use-case for this tag should avoid using it directly. + * + * On compilers without analyzer_noreturn support, this is defined to nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) + + +/** + * A macro to signal that a case statement without a `break` is intentional. + * + * C compilers have gotten more aggressive about warning when a switch's + * `case` block does not end with a `break` or other flow control statement, + * flowing into the next case's code, as this is a common accident that leads + * to strange bugs. But sometimes falling through to the next case is the + * correct and desired behavior. This symbol lets an app communicate this + * intention to the compiler, so it doesn't generate a warning. + * + * It is used like this: + * + * ```c + * switch (x) { + * case 1: + * DoSomethingOnlyForOne(); + * SDL_FALLTHROUGH; // tell the compiler this was intentional. + * case 2: + * DoSomethingForOneAndTwo(); + * break; + * } + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FALLTHROUGH [[fallthrough]] + +/** + * A macro to tag a function's return value as critical. + * + * This is a hint to the compiler that a function's return value should not be + * ignored. + * + * If an NODISCARD function's return value is thrown away (the function is + * called as if it returns `void`), the compiler will issue a warning. + * + * While it's generally good practice to check return values for errors, often + * times legitimate programs do not for good reasons. Be careful about what + * functions are tagged as NODISCARD. It operates best when used on a function + * that's failure is surprising and catastrophic; a good example would be a + * program that checks the return values of all its file write function calls + * but not the call to close the file, which it assumes incorrectly never + * fails. + * + * Function callers that want to throw away a NODISCARD return value can call + * the function with a `(void)` cast, which informs the compiler the act is + * intentional. + * + * On compilers without nodiscard support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NODISCARD [[nodiscard]] + +/** + * A macro to tag a function as an allocator. + * + * This is a hint to the compiler that a function is an allocator, like + * malloc(), with certain rules. A description of how GCC treats this hint is + * here: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute + * + * On compilers without allocator tag support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) + +/** + * A macro to tag a function as returning a certain allocation. + * + * This is a hint to the compiler that a function allocates and returns a + * specific amount of memory based on one of its arguments. For example, the C + * runtime's malloc() function could use this macro with an argument of 1 + * (first argument to malloc is the size of the allocation). + * + * On compilers without alloc_size support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) + +/** + * A macro to tag a pointer variable, to help with pointer aliasing. + * + * A good explanation of the restrict keyword is here: + * + * https://en.wikipedia.org/wiki/Restrict + * + * On compilers without restrict support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_RESTRICT __restrict__ + +/** + * Check if the compiler supports a given builtin functionality. + * + * This allows preprocessor checks for things that otherwise might fail to + * compile. + * + * Supported by virtually all clang versions and more-recent GCCs. Use this + * instead of checking the clang version if possible. + * + * On compilers without has_builtin support, this is defined to 0 (always + * false). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAS_BUILTIN(x) __has_builtin(x) + +/* end of wiki documentation section. */ +#endif + +#ifndef SDL_HAS_BUILTIN +#ifdef __has_builtin +#define SDL_HAS_BUILTIN(x) __has_builtin(x) +#else +#define SDL_HAS_BUILTIN(x) 0 +#endif +#endif + #ifndef SDL_DEPRECATED # if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ # define SDL_DEPRECATED __attribute__((deprecated)) @@ -53,7 +312,7 @@ /* Some compilers use a special export keyword */ #ifndef SDL_DECLSPEC -# if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_CYGWIN) || defined(SDL_PLATFORM_GDK) +# if defined(SDL_PLATFORM_WINDOWS) # ifdef DLL_EXPORT # define SDL_DECLSPEC __declspec(dllexport) # else @@ -70,7 +329,7 @@ /* By default SDL uses the C calling convention */ #ifndef SDLCALL -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_GDK)) && !defined(__GNUC__) +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) #define SDLCALL __cdecl #else #define SDLCALL diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h index 72be082..7435ce6 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -36,10 +36,6 @@ extern "C" { #endif -/** - * \file SDL_bits.h - */ - #if defined(__WATCOMC__) && defined(__386__) extern __inline int _SDL_bsr_watcom(Uint32); #pragma aux _SDL_bsr_watcom = \ @@ -65,7 +61,7 @@ extern __inline int _SDL_bsr_watcom(Uint32); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { @@ -82,10 +78,10 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) return -1; } return _SDL_bsr_watcom(x); -#elif defined(_MSC_VER) +#elif defined(_MSC_VER) && _MSC_VER >= 1400 unsigned long index; if (_BitScanReverse(&index, x)) { - return index; + return (int)index; } return -1; #else @@ -120,8 +116,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * Determine if a unsigned 32-bit value has exactly one bit set. * * If there are no bits set (`x` is zero), or more than one bit set, this - * returns SDL_FALSE. If any one bit is exclusively set, this returns - * SDL_TRUE. + * returns false. If any one bit is exclusively set, this returns true. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is @@ -129,18 +124,18 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine. - * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. + * \returns true if exactly one bit is set in `x`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_HasExactlyOneBitSet32(Uint32 x) +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h index 76aa197..8f00cbc 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,7 @@ * * Blend modes decide how two colors will mix together. There are both * standard modes for basic needs and a means to create custom modes, - * dictating what sort of math to do what on what color components. + * dictating what sort of math to do on what color components. */ #ifndef SDL_blendmode_h_ @@ -45,7 +45,7 @@ extern "C" { * * Additional values may be obtained from SDL_ComposeCustomBlendMode. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_ComposeCustomBlendMode */ @@ -64,7 +64,7 @@ typedef Uint32 SDL_BlendMode; * The blend operation used when combining source and destination pixel * components. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendOperation { @@ -83,7 +83,7 @@ typedef enum SDL_BlendOperation * operation. The comma-separated factors listed above are always applied in * the component order red, green, blue, and alpha. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendFactor { @@ -177,7 +177,9 @@ typedef enum SDL_BlendFactor * \returns an SDL_BlendMode that represents the chosen factors and * operations. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode * \sa SDL_GetRenderDrawBlendMode diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h index 3d4c57e..c4d0596 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -28,13 +28,51 @@ * devices can be enumerated, queried, and opened. Once opened, it will * provide SDL_Surface objects as new frames of video come in. These surfaces * can be uploaded to an SDL_Texture or processed as pixels in memory. + * + * Several platforms will alert the user if an app tries to access a camera, + * and some will present a UI asking the user if your application should be + * allowed to obtain images at all, which they can deny. A successfully opened + * camera will not provide images until permission is granted. Applications, + * after opening a camera device, can see if they were granted access by + * either polling with the SDL_GetCameraPermissionState() function, or waiting + * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED + * event. Platforms that don't have any user approval process will report + * approval immediately. + * + * Note that SDL cameras only provide video as individual frames; they will + * not provide full-motion video encoded in a movie file format, although an + * app is free to encode the acquired frames into any format it likes. It also + * does not provide audio from the camera hardware through this API; not only + * do many webcams not have microphones at all, many people--from streamers to + * people on Zoom calls--will want to use a separate microphone regardless of + * the camera. In any case, recorded audio will be available through SDL's + * audio API no matter what hardware provides the microphone. + * + * ## Camera gotchas + * + * Consumer-level camera hardware tends to take a little while to warm up, + * once the device has been opened. Generally most camera apps have some sort + * of UI to take a picture (a button to snap a pic while a preview is showing, + * some sort of multi-second countdown for the user to pose, like a photo + * booth), which puts control in the users' hands, or they are intended to + * stay on for long times (Pokemon Go, etc). + * + * It's not uncommon that a newly-opened camera will provide a couple of + * completely black frames, maybe followed by some under-exposed images. If + * taking a single frame automatically, or recording video from a camera's + * input without the user initiating it from a preview, it could be wise to + * drop the first several frames (if not the first several _seconds_ worth of + * frames!) before using images from a camera. */ #ifndef SDL_camera_h_ #define SDL_camera_h_ +#include #include -#include +#include +#include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -50,7 +88,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -59,7 +97,7 @@ typedef Uint32 SDL_CameraID; /** * The opaque structure used to identify an opened SDL camera. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Camera SDL_Camera; @@ -69,7 +107,7 @@ typedef struct SDL_Camera SDL_Camera; * Cameras often support multiple formats; each one will be encapsulated in * this struct. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetCameraSupportedFormats * \sa SDL_GetCameraFormat @@ -87,7 +125,7 @@ typedef struct SDL_CameraSpec /** * The position of camera in relation to system device. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCameraPosition */ @@ -116,7 +154,7 @@ typedef enum SDL_CameraPosition * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameraDriver */ @@ -140,7 +178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumCameraDrivers */ @@ -158,7 +196,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); @@ -173,7 +211,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -211,7 +249,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_OpenCamera @@ -227,7 +265,7 @@ extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -246,7 +284,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -265,7 +303,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * You can call SDL_GetCameraFormat() to get the actual data format if passing * a NULL spec here. You can see the exact specs a device can support without - * conversion with SDL_GetCameraSupportedSpecs(). + * conversion with SDL_GetCameraSupportedFormats(). * * SDL will not attempt to emulate framerate; it will try to set the hardware * to the rate closest to the requested speed, but it won't attempt to limit @@ -278,10 +316,11 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * the camera, and they can choose Yes or No at that point. Until they do, the * camera will not be usable. The app should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On - * platforms that don't require explicit user approval (and perhaps in places - * where the user previously permitted access), the approval event might come - * immediately, but it might come seconds, minutes, or hours later! + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. On platforms that don't require explicit user approval (and + * perhaps in places where the user previously permitted access), the approval + * event might come immediately, but it might come seconds, minutes, or hours + * later! * * \param instance_id the camera device instance ID. * \param spec the desired format for data the device will provide. Can be @@ -291,7 +330,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_GetCameraFormat @@ -324,7 +363,7 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera * \sa SDL_CloseCamera @@ -340,7 +379,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -355,7 +394,7 @@ extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera); @@ -366,23 +405,24 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * be converting to this format behind the scenes. * * If the system is waiting for the user to approve access to the camera, as - * some platforms require, this will return SDL_FALSE, but this isn't - * necessarily a fatal error; you should either wait for an + * some platforms require, this will return false, but this isn't necessarily + * a fatal error; you should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. * * \param camera opened camera device. * \param spec the SDL_CameraSpec to be initialized by this function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); /** * Acquire a frame. @@ -404,14 +444,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * After use, the frame should be released with SDL_ReleaseCameraFrame(). If * you don't do this, the system may stop providing more video! * - * Do not call SDL_FreeSurface() on the returned surface! It must be given + * Do not call SDL_DestroySurface() on the returned surface! It must be given * back to the camera subsystem with SDL_ReleaseCameraFrame! * * If the system is waiting for the user to approve access to the camera, as * some platforms require, this will return NULL (no frames available); you * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or - * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() - * occasionally until it returns non-zero. + * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll + * SDL_GetCameraPermissionState() occasionally until it returns non-zero. * * \param camera opened camera device. * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on @@ -421,7 +461,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReleaseCameraFrame */ @@ -449,7 +489,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireCameraFrame */ @@ -464,9 +504,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_ * \threadsafety It is safe to call this function from any thread, but no * thread may reference `device` once this function is called. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_OpenCameraWithSpec * \sa SDL_OpenCamera */ extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h index 4d4ae32..0d3cbb4 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,51 @@ * from other processes and publishing information of its own. * * This is not just text! SDL apps can access and publish data by mimetype. + * + * ## Basic use (text) + * + * Obtaining and publishing simple text to the system clipboard is as easy as + * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively. + * These deal with C strings in UTF-8 encoding. Data transmission and encoding + * conversion is completely managed by SDL. + * + * ## Clipboard callbacks (data other than text) + * + * Things get more complicated when the clipboard contains something other + * than text. Not only can the system clipboard contain data of any type, in + * some cases it can contain the same data in different formats! For example, + * an image painting app might let the user copy a graphic to the clipboard, + * and offers it in .BMP, .JPG, or .PNG format for other apps to consume. + * + * Obtaining clipboard data ("pasting") like this is a matter of calling + * SDL_GetClipboardData() and telling it the mimetype of the data you want. + * But how does one know if that format is available? SDL_HasClipboardData() + * can report if a specific mimetype is offered, and + * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes + * available, so the app can decide what to do with the data and what formats + * it can support. + * + * Setting the clipboard ("copying") to arbitrary data is done with + * SDL_SetClipboardData. The app does not provide the data in this call, but + * rather the mimetypes it is willing to provide and a callback function. + * During the callback, the app will generate the data. This allows massive + * data sets to be provided to the clipboard, without any data being copied + * before it is explicitly requested. More specifically, it allows an app to + * offer data in multiple formats without providing a copy of all of them + * upfront. If the app has an image that it could provide in PNG or JPG + * format, it doesn't have to encode it to either of those unless and until + * something tries to paste it. + * + * ## Primary Selection + * + * The X11 and Wayland video targets have a concept of the "primary selection" + * in addition to the usual clipboard. This is generally highlighted (but not + * explicitly copied) text from various apps. SDL offers APIs for this through + * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers + * these APIs on platforms without this concept, too, but only so far that it + * will keep a copy of a string that the app sets for later retrieval; the + * operating system will not ever attempt to change the string externally if + * it doesn't support a primary selection. */ #ifndef SDL_clipboard_h_ @@ -46,27 +91,31 @@ extern "C" { * Put UTF-8 text into the clipboard. * * \param text the text to store in the clipboard. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_HasClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); /** * Get UTF-8 text from the clipboard. * - * This functions returns empty string if there was not enough memory left for - * a copy of the clipboard's content. + * This functions returns an empty string if there was 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 * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardText * \sa SDL_SetClipboardText @@ -76,40 +125,46 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); /** * Query whether the clipboard exists and contains a non-empty text string. * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * \returns true if the clipboard has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_SetClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * * \param text the text to store in the primary selection. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_HasPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPrimarySelectionText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); /** * Get UTF-8 text from the primary selection. * - * This functions returns empty string if there was not enough memory left for - * a copy of the primary selection's content. + * This functions returns an empty string if there was 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 * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasPrimarySelectionText * \sa SDL_SetPrimarySelectionText @@ -120,15 +175,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * Query whether the primary selection exists and contains a non-empty text * string. * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. + * \returns true if the primary selection has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_SetPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); /** * Callback function that will be called when data for the specified mime-type @@ -148,7 +204,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); * breakage in receiving applications. 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.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -160,7 +216,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c * * \param userdata a pointer to provided user data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -170,13 +226,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * Offer clipboard data to the OS. * * Tell the operating system that the application is offering clipboard data - * for each of the proivded mime-types. Once another application requests the - * data the callback function will be called allowing it to generate and + * for each of the provided mime-types. Once another application requests the + * data the callback function will be called, allowing it to generate and * 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 - * document) + * document). * * \param callback a function pointer to the function that provides the * clipboard data. @@ -185,28 +241,32 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \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 num_mime_types the number of mime-types in the mime_types list. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearClipboardData * \sa SDL_GetClipboardData * \sa SDL_HasClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** * Clear the clipboard data. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); /** * Get the data from clipboard for a given mime type. @@ -220,7 +280,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); * for more information. This should be freed with SDL_free() when it * is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardData * \sa SDL_SetClipboardData @@ -231,15 +293,34 @@ 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 SDL_TRUE if there exists data in clipboard for the provided mime - * type, SDL_FALSE if it does not. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData * \sa SDL_GetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \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 + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h index fa4d3d1..da1dea7 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -21,7 +21,10 @@ /* * This file reverses the effects of SDL_begin_code.h and should be included - * after you finish any function and structure declarations in your headers + * after you finish any function and structure declarations in your headers. + * + * SDL's headers use this; applications generally should not include this + * header directly. */ #ifndef SDL_begin_code_h diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h index dcbdcea..747bd35 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h index e7ced26..1745bd9 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,6 +29,12 @@ * These functions are largely concerned with reporting if the system has * access to various SIMD instruction sets, but also has other important info * to share, such as system RAM size and number of logical CPU cores. + * + * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are + * available on all platforms, even if they don't make sense (an ARM processor + * will never have SSE and an x86 processor will never have NEON, for example, + * but these functions still exist and will simply return false in these + * cases). */ #ifndef SDL_cpuinfo_h_ @@ -49,20 +55,22 @@ extern "C" { * processors have a 128 byte cache line. We use the larger value to be * generally safe. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CACHELINE_SIZE 128 /** - * Get the number of CPU cores available. + * Get the number of logical CPU cores available. * * \returns the total number of logical CPU cores. On CPUs that include * technologies such as hyperthreading, the number of logical cores * may be more than the number of physical cores. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); /** * Determine the L1 cache line size of the CPU. @@ -72,7 +80,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); * * \returns the L1 cache line size of the CPU, in bytes. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); @@ -82,144 +92,164 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * This always returns false on CPUs that aren't using PowerPC instruction * sets. * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. + * \returns true if the CPU has AltiVec features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); /** * Determine whether the CPU has MMX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. + * \returns true if the CPU has MMX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); /** * Determine whether the CPU has SSE features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. + * \returns true if the CPU has SSE features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); /** * Determine whether the CPU has SSE2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); /** * Determine whether the CPU has SSE3 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. + * \returns true if the CPU has SSE3 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); /** * Determine whether the CPU has SSE4.1 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.1 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); /** * Determine whether the CPU has SSE4.2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); /** * Determine whether the CPU has AVX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. + * \returns true if the CPU has AVX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX2 * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); /** * Determine whether the CPU has AVX2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. + * \returns true if the CPU has AVX2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); /** * Determine whether the CPU has AVX-512F (foundation) features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. + * \returns true if the CPU has AVX-512F features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX2 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); /** * Determine whether the CPU has ARM SIMD (ARMv6) features. @@ -228,24 +258,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. + * \returns true if the CPU has ARM SIMD features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasNEON */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); /** * Determine whether the CPU has NEON (ARM SIMD) features. * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. + * \returns true if the CPU has ARM NEON features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); /** * Determine whether the CPU has LSX (LOONGARCH SIMD) features. @@ -253,12 +287,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LSX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); /** * Determine whether the CPU has LASX (LOONGARCH SIMD) features. @@ -266,19 +301,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LASX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); /** * Get the amount of RAM configured in the system. * * \returns the amount of RAM configured in the system in MiB. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); @@ -297,7 +335,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); * \returns the alignment in bytes needed for available, known SIMD * instructions. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc * \sa SDL_aligned_free diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h index 8a198a8..460038f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,12 +23,23 @@ * # CategoryDialog * * File dialog support. + * + * SDL offers file dialogs, to let users select files with native GUI + * interfaces. There are "open" dialogs, "save" dialogs, and folder selection + * dialogs. The app can control some details, such as filtering to specific + * files, or whether multiple files can be selected by the user. + * + * Note that launching a file dialog is a non-blocking operation; control + * returns to the app immediately, and a callback is called later (possibly in + * another thread) when the user makes a choice. */ #ifndef SDL_dialog_h_ #define SDL_dialog_h_ +#include #include +#include #include #include @@ -48,12 +59,13 @@ extern "C" { * hyphens, underscores and periods. Alternatively, the whole string can be a * single asterisk ("*"), which serves as an "All files" filter. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef struct SDL_DialogFileFilter { @@ -75,31 +87,34 @@ typedef struct SDL_DialogFileFilter * is a null-terminated list of pointers to C strings, each containing a * path. * - * The filelist argument does not need to be freed; it will automatically be - * freed when the callback returns. + * The filelist argument should not be freed; it will automatically be freed + * when the callback returns. * * The filter argument is the index of the filter that was selected, or -1 if * no filter was selected or if the platform or method doesn't support * fetching the selected filter. * + * In Android, the `filelist` are `content://` URIs. They should be opened + * using SDL_IOFromFile() with appropriate modes. This applies both to open + * and save file dialog. + * * \param userdata an app-provided pointer, for the callback's use. * \param filelist the file(s) chosen by the user. * \param filter index of the selected filter. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter); /** * Displays a dialog that lets the user select a file on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -117,47 +132,41 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); /** * Displays a dialog that lets the user choose a new or existing file on their * filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -174,44 +183,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); /** * Displays a dialog that lets the user select a folder on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -229,31 +232,105 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is always -1 for SDL_ShowOpenFolderDialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \param window the window that the dialog should be modal for, may be NULL. * Not all platforms support this option. - * \param default_location the default folder or file to start the dialog at. - * May be NULL. Not all platforms support this option. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); + +/** + * Various types of file dialogs. + * + * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of + * dialog to present to the user. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ShowFileDialogWithProperties + */ +typedef enum SDL_FileDialogType +{ + SDL_FILEDIALOG_OPENFILE, + SDL_FILEDIALOG_SAVEFILE, + SDL_FILEDIALOG_OPENFOLDER +} SDL_FileDialogType; + +/** + * Create and launch a file dialog with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of + * SDL_DialogFileFilter structs, which will be used as filters for + * file-based selections. Ignored if the dialog is an "Open Folder" dialog. + * If non-NULL, the array of filters must remain valid at least until the + * callback is invoked. + * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the + * array of filters, if it exists. + * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should + * be modal for. + * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to + * start the dialog at. + * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select + * more than one entry. + * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. + * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button + * should have. + * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button + * should have. + * + * Note that each platform may or may not support any of the properties. + * + * \param type the type of file dialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param props the properties to use. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FileDialogType + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); + +#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" +#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" +#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" +#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" +#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" +#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" +#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" +#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -261,4 +338,4 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback #endif #include -#endif /* SDL_joystick_h_ */ +#endif /* SDL_dialog_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h index cc557d6..65d4e96 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h index cb3d7f3..a34e9d4 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,20 @@ /** * # CategoryEndian * - * Functions for reading and writing endian-specific values. + * Functions converting endian-specific values to different byte orders. + * + * These functions either unconditionally swap byte order (SDL_Swap16, + * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's + * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, + * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the + * latter case, the functionality is provided by macros that become no-ops if + * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE + * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC + * processor (bigendian), the macros behavior is reversed. + * + * The swap routines are inline functions, and attempt to use compiler + * intrinsics, inline assembly, and other magic to make byteswapping + * efficient. */ #ifndef SDL_endian_h_ @@ -51,12 +64,71 @@ _m_prefetch(void *__P) * \name The two types of endianness */ /* @{ */ + + +/** + * A value to represent littleendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_LIL_ENDIAN + * SDL_Log("This system is littleendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_BIG_ENDIAN + */ #define SDL_LIL_ENDIAN 1234 + +/** + * A value to represent bigendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_LIL_ENDIAN + */ #define SDL_BIG_ENDIAN 4321 + /* @} */ #ifndef SDL_BYTEORDER -#ifdef SDL_PLATFORM_LINUX +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's byte order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +#elif defined(SDL_PLATFORM_LINUX) #include #define SDL_BYTEORDER __BYTE_ORDER #elif defined(SDL_PLATFORM_SOLARIS) @@ -97,8 +169,29 @@ _m_prefetch(void *__P) #endif /* !SDL_BYTEORDER */ #ifndef SDL_FLOATWORDORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's floating point word order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN + * SDL_Log("This system's floats are bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN /* predefs from newer gcc versions: */ -#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) #if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) #define SDL_FLOATWORDORDER SDL_LIL_ENDIAN #elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) @@ -125,10 +218,6 @@ _m_prefetch(void *__P) extern "C" { #endif -/** - * \file SDL_endian.h - */ - /* various modern compilers may have builtin swap */ #if defined(__GNUC__) || defined(__clang__) # define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \ @@ -148,6 +237,7 @@ extern "C" { #endif /* Byte swap 16-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP16 #define SDL_Swap16(x) __builtin_bswap16(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -191,8 +281,10 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); } #endif +#endif /* Byte swap 32-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP32 #define SDL_Swap32(x) __builtin_bswap32(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -239,8 +331,10 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) ((x >> 8) & 0x0000FF00) | (x >> 24))); } #endif +#endif /* Byte swap 64-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP64 #define SDL_Swap64(x) __builtin_bswap64(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -290,7 +384,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) return (x); } #endif - +#endif /** * Byte-swap a floating point number. @@ -309,7 +403,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { @@ -348,7 +442,7 @@ SDL_FORCE_INLINE float SDL_SwapFloat(float x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } @@ -369,7 +463,7 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } @@ -390,7 +484,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } @@ -404,7 +498,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16LE(x) SwapOnlyIfNecessary(x) @@ -418,7 +514,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32LE(x) SwapOnlyIfNecessary(x) @@ -432,7 +530,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64LE(x) SwapOnlyIfNecessary(x) @@ -446,7 +546,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x) @@ -460,7 +562,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16BE(x) SwapOnlyIfNecessary(x) @@ -474,7 +578,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32BE(x) SwapOnlyIfNecessary(x) @@ -488,7 +594,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64BE(x) SwapOnlyIfNecessary(x) @@ -502,7 +610,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x) diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h index a98823f..934967c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,26 @@ * # CategoryError * * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. */ #ifndef SDL_error_h_ @@ -44,8 +64,8 @@ extern "C" { * * Calling this function will replace any previous error message that was set. * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: * * ```c * if (error_code) { @@ -56,25 +76,49 @@ extern "C" { * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if * any. - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_GetError + * \sa SDL_SetErrorV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * \param fmt a printf()-style message format string. + * \param ap a variable argument list. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1); /** * Set an error indicating that memory allocation failed. * * This function does not do any memory allocation. * - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); /** * Retrieve a message about the last error that occurred on the current @@ -104,7 +148,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); * or an empty string if there hasn't been an error message set since * the last call to SDL_ClearError(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_SetError @@ -114,14 +160,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); /** * Clear any previous error message for this thread. * - * \returns SDL_TRUE. + * \returns true. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetError * \sa SDL_SetError */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); /** * \name Internal error functions @@ -130,8 +178,43 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); * Private error reporting function - used internally. */ /* @{ */ + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_Unsupported() SDL_SetError("That operation is not supported") + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * A common usage pattern inside SDL is this: + * + * ```c + * bool MyFunction(const char *str) { + * if (!str) { + * return SDL_InvalidParamError("str"); // returns false. + * } + * DoSomething(str); + * return true; + * } + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + /* @} *//* Internal error functions */ /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h index fbe2bb0..1323e9f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,22 +23,50 @@ * # CategoryEvents * * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. */ #ifndef SDL_events_h_ #define SDL_events_h_ +#include #include +#include #include #include #include #include +#include #include #include -#include +#include +#include +#include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,29 +76,10 @@ extern "C" { /* General keyboard/mouse/pen state definitions */ -/** - * A value that signifies a button is no longer pressed. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_PRESSED - */ -#define SDL_RELEASED 0 - -/** - * A value that signifies a button has been pressed down. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_RELEASED - */ -#define SDL_PRESSED 1 - - /** * The types of events that can be delivered. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_EventType { @@ -148,7 +157,7 @@ typedef enum SDL_EventType SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */ SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */ SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled - in an event watcher, the window handle is still valid and can still be used to retrieve any userdata + in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid */ SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ @@ -203,6 +212,7 @@ typedef enum SDL_EventType SDL_EVENT_FINGER_DOWN = 0x700, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, + SDL_EVENT_FINGER_CANCELED, /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ @@ -243,6 +253,13 @@ typedef enum SDL_EventType /* Render events */ SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ + SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + SDL_EVENT_PRIVATE0 = 0x4000, + SDL_EVENT_PRIVATE1, + SDL_EVENT_PRIVATE2, + SDL_EVENT_PRIVATE3, /* Internal events */ SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ @@ -265,7 +282,7 @@ typedef enum SDL_EventType /** * Fields shared by every event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CommonEvent { @@ -277,7 +294,7 @@ typedef struct SDL_CommonEvent /** * Display state change event data (event.display.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DisplayEvent { @@ -292,7 +309,7 @@ typedef struct SDL_DisplayEvent /** * Window state change event data (event.window.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_WindowEvent { @@ -307,7 +324,7 @@ typedef struct SDL_WindowEvent /** * Keyboard device event structure (event.kdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_KeyboardDeviceEvent { @@ -326,7 +343,7 @@ typedef struct SDL_KeyboardDeviceEvent * event scancode and modifiers directly from the keyboard layout, bypassing * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_HINT_KEYCODE_OPTIONS @@ -342,8 +359,8 @@ typedef struct SDL_KeyboardEvent SDL_Keycode key; /**< SDL virtual key code */ SDL_Keymod mod; /**< current key modifiers */ Uint16 raw; /**< The platform dependent scancode for this event */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ } SDL_KeyboardEvent; /** @@ -353,7 +370,7 @@ typedef struct SDL_KeyboardEvent * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingEvent { @@ -369,7 +386,7 @@ typedef struct SDL_TextEditingEvent /** * Keyboard IME candidates event structure (event.edit_candidates.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingCandidatesEvent { @@ -380,7 +397,10 @@ typedef struct SDL_TextEditingCandidatesEvent const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ Sint32 num_candidates; /**< The number of strings in `candidates` */ Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ - SDL_bool horizontal; /**< SDL_TRUE if the list is horizontal, SDL_FALSE if it's vertical */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_TextEditingCandidatesEvent; /** @@ -389,7 +409,7 @@ typedef struct SDL_TextEditingCandidatesEvent * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput @@ -406,7 +426,7 @@ typedef struct SDL_TextInputEvent /** * Mouse device event structure (event.mdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseDeviceEvent { @@ -419,7 +439,7 @@ typedef struct SDL_MouseDeviceEvent /** * Mouse motion event structure (event.motion.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseMotionEvent { @@ -427,7 +447,7 @@ typedef struct SDL_MouseMotionEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id or SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ SDL_MouseButtonFlags state; /**< The current button state */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ @@ -438,7 +458,7 @@ typedef struct SDL_MouseMotionEvent /** * Mouse button event structure (event.button.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseButtonEvent { @@ -446,9 +466,9 @@ typedef struct SDL_MouseButtonEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding; float x; /**< X coordinate, relative to window */ @@ -458,7 +478,7 @@ typedef struct SDL_MouseButtonEvent /** * Mouse wheel event structure (event.wheel.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseWheelEvent { @@ -466,7 +486,7 @@ typedef struct SDL_MouseWheelEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */ float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ @@ -477,7 +497,7 @@ typedef struct SDL_MouseWheelEvent /** * Joystick axis motion event structure (event.jaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyAxisEvent { @@ -496,7 +516,7 @@ typedef struct SDL_JoyAxisEvent /** * Joystick trackball motion event structure (event.jball.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBallEvent { @@ -515,7 +535,7 @@ typedef struct SDL_JoyBallEvent /** * Joystick hat position change event structure (event.jhat.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyHatEvent { @@ -538,7 +558,7 @@ typedef struct SDL_JoyHatEvent /** * Joystick button event structure (event.jbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyButtonEvent { @@ -547,7 +567,7 @@ typedef struct SDL_JoyButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; @@ -555,7 +575,12 @@ typedef struct SDL_JoyButtonEvent /** * Joystick device event structure (event.jdevice.*) * - * \since This struct is available since SDL 3.0.0. + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GamepadDeviceEvent */ typedef struct SDL_JoyDeviceEvent { @@ -566,9 +591,9 @@ typedef struct SDL_JoyDeviceEvent } SDL_JoyDeviceEvent; /** - * Joysick battery level change event structure (event.jbattery.*) + * Joystick battery level change event structure (event.jbattery.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBatteryEvent { @@ -583,7 +608,7 @@ typedef struct SDL_JoyBatteryEvent /** * Gamepad axis motion event structure (event.gaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadAxisEvent { @@ -603,7 +628,7 @@ typedef struct SDL_GamepadAxisEvent /** * Gamepad button event structure (event.gbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadButtonEvent { @@ -612,7 +637,7 @@ typedef struct SDL_GamepadButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_GamepadButtonEvent; @@ -621,7 +646,16 @@ typedef struct SDL_GamepadButtonEvent /** * Gamepad device event structure (event.gdevice.*) * - * \since This struct is available since SDL 3.0.0. + * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent + * and an SDL_GamepadDeviceEvent. + * + * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged + * in during SDL_Init() and are recognized as gamepads. It will also send + * events for joysticks that get gamepad mappings at runtime. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_JoyDeviceEvent */ typedef struct SDL_GamepadDeviceEvent { @@ -634,7 +668,7 @@ typedef struct SDL_GamepadDeviceEvent /** * Gamepad touchpad event structure (event.gtouchpad.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadTouchpadEvent { @@ -652,7 +686,7 @@ typedef struct SDL_GamepadTouchpadEvent /** * Gamepad sensor event structure (event.gsensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadSensorEvent { @@ -668,7 +702,7 @@ typedef struct SDL_GamepadSensorEvent /** * Audio device event structure (event.adevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AudioDeviceEvent { @@ -676,7 +710,7 @@ typedef struct SDL_AudioDeviceEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ - Uint8 recording; /**< zero if a playback device, non-zero if a recording device. */ + bool recording; /**< false if a playback device, true if a recording device. */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -685,7 +719,7 @@ typedef struct SDL_AudioDeviceEvent /** * Camera device event structure (event.cdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CameraDeviceEvent { @@ -695,14 +729,43 @@ typedef struct SDL_CameraDeviceEvent SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ } SDL_CameraDeviceEvent; + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RenderEvent +{ + SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window containing the renderer in question. */ +} SDL_RenderEvent; + + /** * Touch finger event structure (event.tfinger.*) * - * \since This struct is available since SDL 3.0.0. + * Coordinates in this event are normalized. `x` and `y` are normalized to a + * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top + * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are + * normalized in the ranges of -1.0f (traversed all the way from the bottom or + * right to all the way up or left) to 1.0f (traversed all the way from the + * top or left to all the way down or right). + * + * Note that while the coordinates are _normalized_, they are not _clamped_, + * which means in some circumstances you can get a value outside of this + * range. For example, a renderer using logical presentation might give a + * negative value when the touch is in the letterboxing. Some platforms might + * report a touch outside of the window, which will also be outside of the + * range. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TouchFingerEvent { - SDL_EventType type; /**< SDL_EVENT_FINGER_MOTION or SDL_EVENT_FINGER_DOWN or SDL_EVENT_FINGER_UP */ + SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_TouchID touchID; /**< The touch device id */ @@ -728,14 +791,14 @@ typedef struct SDL_TouchFingerEvent * is there." The pen touching and lifting off from the tablet while not * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenProximityEvent { SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ } SDL_PenProximityEvent; @@ -748,18 +811,18 @@ typedef struct SDL_PenProximityEvent * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when * dealing with pen motion. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenMotionEvent { SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ } SDL_PenMotionEvent; /** @@ -768,7 +831,7 @@ typedef struct SDL_PenMotionEvent * These events come when a pen touches a surface (a tablet, etc), or lifts * off from one. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenTouchEvent { @@ -778,10 +841,10 @@ typedef struct SDL_PenTouchEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ - Uint8 eraser; /**< Non-zero if eraser end is used (not all pens support this). */ - Uint8 state; /**< SDL_PRESSED (pen is touching) or SDL_RELEASED (pen is lifted off) */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ } SDL_PenTouchEvent; /** @@ -790,7 +853,7 @@ typedef struct SDL_PenTouchEvent * This is for buttons on the pen itself that the user might click. The pen * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenButtonEvent { @@ -800,10 +863,10 @@ typedef struct SDL_PenButtonEvent SDL_WindowID windowID; /**< The window with mouse focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ Uint8 button; /**< The pen button index (first button is 1). */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ } SDL_PenButtonEvent; /** @@ -812,7 +875,7 @@ typedef struct SDL_PenButtonEvent * You might get some of these events even if the pen isn't touching the * tablet. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenAxisEvent { @@ -822,8 +885,8 @@ typedef struct SDL_PenAxisEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ SDL_PenAxis axis; /**< Axis that has changed */ float value; /**< New value of axis */ } SDL_PenAxisEvent; @@ -832,7 +895,7 @@ typedef struct SDL_PenAxisEvent * An event used to drop text or request a file open by the system * (event.drop.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DropEvent { @@ -850,19 +913,22 @@ typedef struct SDL_DropEvent * An event triggered when the clipboard contents have changed * (event.clipboard.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_ClipboardEvent { SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + bool owner; /**< are we owning the clipboard (internal update) */ + Sint32 num_mime_types; /**< number of mime types */ + const char **mime_types; /**< current mime types */ } SDL_ClipboardEvent; /** * Sensor event structure (event.sensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_SensorEvent { @@ -877,7 +943,7 @@ typedef struct SDL_SensorEvent /** * The "quit requested" event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_QuitEvent { @@ -895,7 +961,7 @@ typedef struct SDL_QuitEvent * the programmer; the only requirement is that '''type''' is a value obtained * from SDL_RegisterEvents(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_UserEvent { @@ -912,7 +978,10 @@ typedef struct SDL_UserEvent /** * The structure for all events in SDL. * - * \since This struct is available since SDL 3.0.0. + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. + * + * \since This struct is available since SDL 3.2.0. */ typedef union SDL_Event { @@ -951,6 +1020,7 @@ typedef union SDL_Event SDL_PenMotionEvent pmotion; /**< Pen motion event data */ SDL_PenButtonEvent pbutton; /**< Pen button event data */ SDL_PenAxisEvent paxis; /**< Pen axis event data */ + SDL_RenderEvent render; /**< Render event data */ SDL_DropEvent drop; /**< Drag and drop event data */ SDL_ClipboardEvent clipboard; /**< Clipboard event data */ @@ -981,10 +1051,6 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * * This function updates the event queue and internal input device state. * - * **WARNING**: This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider only doing those - * things on the main thread in any case. - * * SDL_PumpEvents() gathers all the pending input information from devices and * places it in the event queue. Without calls to SDL_PumpEvents() no events * would ever be placed on the queue. Often the need for calls to @@ -993,7 +1059,9 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * polling or waiting for events (e.g. you are filtering them), then you must * call SDL_PumpEvents() to force an event queue update. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent @@ -1001,11 +1069,17 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_EventAction { - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ } SDL_EventAction; /** @@ -1017,7 +1091,9 @@ typedef enum SDL_EventAction * event queue. * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. + * caller and will _not_ be removed from the queue. If you pass NULL for + * `events`, then `numevents` is ignored and the total number of matching + * events will be returned. * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the * caller and will be removed from the queue. @@ -1026,8 +1102,6 @@ typedef enum SDL_EventAction * Otherwise, the events may not be ready to be filtered when you call * SDL_PeepEvents(). * - * This function is thread-safe. - * * \param events destination buffer for the retrieved events, may be NULL to * leave the events in the queue and return the number of events * that would have been stored. @@ -1042,7 +1116,9 @@ typedef enum SDL_EventAction * \returns the number of events actually stored or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PumpEvents @@ -1058,14 +1134,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, * instead. * * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); /** @@ -1077,14 +1155,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); /** * Clear events of a specific type from the event queue. @@ -1106,7 +1186,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp * * \param type the type of event to be cleared; see SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvents */ @@ -1131,7 +1213,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * \param maxType the high end of event type to be cleared, inclusive; see * SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvent */ @@ -1171,16 +1255,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * * \param event the SDL_Event structure to be filled with the next event from * the queue, or NULL. - * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none - * available. + * \returns true if this got an event or false if there are none available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent * \sa SDL_WaitEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); /** * Wait indefinitely for the next available event. @@ -1193,16 +1278,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * * \param event the SDL_Event structure to be filled in with the next event * from the queue, or NULL. - * \returns SDL_TRUE on success or SDL_FALSE if there was an error while - * waiting for events; call SDL_GetError() for more information. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); /** * Wait until the specified timeout (in milliseconds) for the next available @@ -1221,16 +1308,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * from the queue, or NULL. * \param timeoutMS the maximum number of milliseconds to wait for the next * available event. - * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed - * without any events available. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEvent */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); /** * Add an event to the event queue. @@ -1244,8 +1333,6 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * Note: Pushing device input events onto the queue doesn't modify the state * of the device within SDL. * - * This function is thread-safe, and can be called from other threads safely. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter but events added with SDL_PeepEvents() do not. * @@ -1254,17 +1341,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * its own custom event types. * * \param event the SDL_Event to be added to the queue. - * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on - * failure; call SDL_GetError() for more information. A common reason - * for error is the event queue being full. + * \returns true on success, false if the event was filtered or on failure; + * call SDL_GetError() for more information. A common reason for + * error is the event queue being full. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PeepEvents * \sa SDL_PollEvent * \sa SDL_RegisterEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); /** * A function pointer used for callbacks that watch the event queue. @@ -1272,29 +1361,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * SDL_AddEventWatch, etc. * \param event the event that triggered the callback. - * \returns SDL_TRUE to permit event to be added to the queue, and SDL_FALSE - * to disallow it. When used with SDL_AddEventWatch, the return value - * is ignored. + * \returns true to permit event to be added to the queue, and false to + * disallow it. When used with SDL_AddEventWatch, the return value is + * ignored. * * \threadsafety SDL may call this callback at any time from any thread; the * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetEventFilter * \sa SDL_AddEventWatch */ -typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. * - * If the filter function returns SDL_TRUE when called, then the event will be - * added to the internal queue. If it returns SDL_FALSE, then the event will - * be dropped from the queue, but the internal state will still be updated. - * This allows selective filtering of dynamically arriving events. + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. + * + * If the filter function returns true when called, then the event will be + * added to the internal queue. If it returns false, then the event will be + * dropped from the queue, but the internal state will still be updated. This + * allows selective filtering of dynamically arriving events. * * **WARNING**: Be very careful of what you do in the event filter function, * as it may run in a different thread! @@ -1303,17 +1395,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. @@ -1321,11 +1405,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \threadsafety SDL may call the filter callback at any time from any thread; - * the application is responsible for locking resources the - * callback touches that need to be protected. + * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch * \sa SDL_SetEventEnabled @@ -1344,13 +1426,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void * \param filter the current callback function will be stored here. * \param userdata the pointer that is passed to the current event filter will * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. + * \returns true on success or false if there is no event filter set. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); /** * Add a callback to be triggered when an event is added to the event queue. @@ -1372,17 +1456,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, * * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); /** * Remove an event watch callback added with SDL_AddEventWatch(). @@ -1393,7 +1477,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, v * \param filter the function originally passed to SDL_AddEventWatch(). * \param userdata the pointer originally passed to SDL_AddEventWatch(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -1401,7 +1487,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo /** * Run a specific filter function on the current event queue, removing any - * events for which the filter returns SDL_FALSE. + * events for which the filter returns false. * * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), * this function does not change the filter permanently, it only uses the @@ -1410,7 +1496,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo * \param filter the SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetEventFilter * \sa SDL_SetEventFilter @@ -1423,23 +1511,27 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void * * \param type the type of event; see SDL_EventType for details. * \param enabled whether to process the event or not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EventEnabled */ -extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); /** * Query the state of processing events by type. * * \param type the type of event; see SDL_EventType for details. - * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. + * \returns true if the event is being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); /** * Allocate a set of user-defined events, and return the beginning event @@ -1449,7 +1541,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); * \returns the beginning event number, or 0 if numevents is invalid or if * there are not enough user-defined events left. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent */ @@ -1461,7 +1555,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); * \param event an event containing a `windowID`. * \returns the associated window on success or NULL if there is none. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h index 5faa244..af3ca27 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,23 @@ /** * # CategoryFilesystem * - * SDL Filesystem API. + * SDL offers an API for examining and manipulating the system's filesystem. + * This covers most things one would need to do with directories, except for + * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) + * and [CategoryAsyncIO](CategoryAsyncIO) instead). + * + * There are functions to answer necessary path questions: + * + * - Where is my app's data? SDL_GetBasePath(). + * - Where can I safely write files? SDL_GetPrefPath(). + * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder(). + * - What is this thing at this location? SDL_GetPathInfo(). + * - What items live in this folder? SDL_EnumerateDirectory(). + * - What items live in this folder by wildcard? SDL_GlobDirectory(). + * - What is my current working directory? SDL_GetCurrentDirectory(). + * + * SDL also offers functions to manipulate the directory tree: renaming, + * removing, copying files. */ #ifndef SDL_filesystem_h_ @@ -73,7 +89,7 @@ extern "C" { * doesn't implement this functionality, call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrefPath */ @@ -128,7 +144,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); * etc.). This should be freed with SDL_free() when it is no longer * needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBasePath */ @@ -143,66 +159,40 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * * * The folders supported per platform are: * - * | | Windows | WinRT/UWP |macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | - * | ----------- | ------- | --------- |--------- | ---- | ---------- | ----- | ---------- | - * | HOME | X | X | X | | X | X | X | - * | DESKTOP | X | X | X | | X | X | | - * | DOCUMENTS | X | X | X | | X | | | - * | DOWNLOADS | Vista+ | X | X | | X | | | - * | MUSIC | X | X | X | | X | | | - * | PICTURES | X | X | X | | X | | | - * | PUBLICSHARE | | | X | | X | | | - * | SAVEDGAMES | Vista+ | | | | | | | - * | SCREENSHOTS | Vista+ | X | | | | | | - * | TEMPLATES | X | X | X | | X | | | - * | VIDEOS | X | X | X* | | X | | | + * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | + * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- | + * | HOME | X | X | | X | X | X | + * | DESKTOP | X | X | | X | X | | + * | DOCUMENTS | X | X | | X | | | + * | DOWNLOADS | Vista+ | X | | X | | | + * | MUSIC | X | X | | X | | | + * | PICTURES | X | X | | X | | | + * | PUBLICSHARE | | X | | X | | | + * | SAVEDGAMES | Vista+ | | | | | | + * | SCREENSHOTS | Vista+ | | | | | | + * | TEMPLATES | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | * * Note that on macOS/iOS, the Videos folder is called "Movies". * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetUserFolder */ typedef enum SDL_Folder { - /** The folder which contains all of the current user's data, preferences, - and documents. It usually contains most of the other folders. If a - requested folder does not exist, the home folder can be considered a safe - fallback to store a user's documents. */ - SDL_FOLDER_HOME, - /** The folder of files that are displayed on the desktop. Note that the - existence of a desktop folder does not guarantee that the system does - show icons on its desktop; certain GNU/Linux distros with a graphical - environment may not have desktop icons. */ - SDL_FOLDER_DESKTOP, - /** User document files, possibly application-specific. This is a good - place to save a user's projects. */ - SDL_FOLDER_DOCUMENTS, - /** Standard folder for user files downloaded from the internet. */ - SDL_FOLDER_DOWNLOADS, - /** Music files that can be played using a standard music player (mp3, - ogg...). */ - SDL_FOLDER_MUSIC, - /** Image files that can be displayed using a standard viewer (png, - jpg...). */ - SDL_FOLDER_PICTURES, - /** Files that are meant to be shared with other users on the same - computer. */ - SDL_FOLDER_PUBLICSHARE, - /** Save files for games. */ - SDL_FOLDER_SAVEDGAMES, - /** Application screenshots. */ - SDL_FOLDER_SCREENSHOTS, - /** Template files to be used when the user requests the desktop environment - to create a new file in a certain folder, such as "New Text File.txt". - Any file in the Templates folder can be used as a starting point for a - new file. */ - SDL_FOLDER_TEMPLATES, - /** Video files that can be played using a standard video player (mp4, - webm...). */ - SDL_FOLDER_VIDEOS, - /** total number of types in this enum, not a folder type by itself. */ - SDL_FOLDER_TOTAL + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ } SDL_Folder; /** @@ -226,13 +216,24 @@ typedef enum SDL_Folder * \returns either a null-terminated C string containing the full path to the * folder, or NULL if an error happened. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder); /* Abstract filesystem interface */ +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ typedef enum SDL_PathType { SDL_PATHTYPE_NONE, /**< path does not exist */ @@ -241,19 +242,27 @@ typedef enum SDL_PathType SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */ } SDL_PathType; +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ typedef struct SDL_PathInfo { - SDL_PathType type; /* the path type */ - Uint64 size; /* the file size in bytes */ - SDL_Time create_time; /* the time when the path was created */ - SDL_Time modify_time; /* the last time the path was modified */ - SDL_Time access_time; /* the last time the path was read */ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ } SDL_PathInfo; /** - * Flags for path matching + * Flags for path matching. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GlobDirectory * \sa SDL_GlobStorageDirectory @@ -263,73 +272,160 @@ typedef Uint32 SDL_GlobFlags; #define SDL_GLOB_CASEINSENSITIVE (1u << 0) /** - * Create a directory. + * Create a directory, and any missing parent directories. + * + * This reports success if `path` already exists as a directory. + * + * If parent directories are missing, it will also create them. Note that if + * this fails, it will not remove any parent directories it already made. * * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateDirectory(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); -/* Callback for directory enumeration. Return 1 to keep enumerating, - 0 to stop enumerating (no error), -1 to stop enumerating and - report an error. `dirname` is the directory being enumerated, - `fname` is the enumerated entry. */ -typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param dirname the directory that is being enumerated. + * \param fname the next entry in the enumeration. + * \returns how the enumeration should proceed. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); /** * Enumerate a directory through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. * * \param path the path of the directory to enumerate. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory. * - * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. * - * \since This function is available since SDL 3.0.0. + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemovePath(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); /** * Rename a file or directory. * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); /** * Copy a file. * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `newpath`'s previous contents will be gone, replaced with + * an incomplete copy of the data. To avoid this risk, it is recommended that + * the app copy to a temporary file in the same directory as `newpath`, and if + * the copy is successful, use SDL_RenamePath() to replace `newpath` with the + * temporary file. This will ensure that reads of `newpath` will either see a + * complete copy of the data, or it will see the pre-copy state of `newpath`. + * + * This function attempts to synchronize the newly-copied data to disk before + * returning, if the platform allows it, so that the renaming trick will not + * have a problem in a system crash or power failure, where the file could be + * renamed but the contents never made it from the system file cache to the + * physical disk. + * + * If the copy fails for any reason, the state of `newpath` is undefined. It + * might be half a copy, it might be the untouched data of what was already + * there, or it might be a zero-byte file, etc. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); /** * Get information about a filesystem path. @@ -337,21 +433,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const cha * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); /** * Enumerate a directory tree, filtered by pattern, and return a list. * * Files are filtered out if they don't match the string in `pattern`, which - * may contain wildcard characters '*' (match everything) and '?' (match one + * may contain wildcard characters '\*' (match everything) and '?' (match one * character). If pattern is NULL, no filtering is done and all results are * returned. Subdirectories are permitted, and are specified with a path - * separator of '/'. Wildcard characters '*' and '?' never match a path + * separator of '/'. Wildcard characters '\*' and '?' never match a path * separator. * * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching @@ -373,10 +469,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count); +/** + * Get what the system believes is the "current working directory." + * + * For systems without a concept of a current working directory, this will + * still attempt to provide something reasonable. + * + * SDL does not provide a means to _change_ the current working directory; for + * platforms without this concept, this would cause surprises with file access + * outside of SDL. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns a UTF-8 string of the current working directory in + * platform-dependent notation. NULL if there's a problem. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h index 3d2d726..264f763 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,6 +51,24 @@ * If you would like to receive gamepad updates while the application is in * the background, you should set the following hint before calling * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. */ #ifndef SDL_gamepad_h_ @@ -58,9 +76,11 @@ #include #include -#include -#include +#include #include +#include +#include +#include #include #include @@ -72,7 +92,7 @@ extern "C" { /** * The structure used to identify an SDL gamepad * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Gamepad SDL_Gamepad; @@ -98,7 +118,7 @@ typedef enum SDL_GamepadType SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_GAMEPAD_TYPE_MAX + SDL_GAMEPAD_TYPE_COUNT } SDL_GamepadType; /** @@ -122,15 +142,15 @@ typedef enum SDL_GamepadType * You can query the labels for the face buttons using * SDL_GetGamepadButtonLabel() * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButton { SDL_GAMEPAD_BUTTON_INVALID = -1, - SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */ - SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */ - SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */ - SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */ + SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */ + SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */ + SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */ + SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */ SDL_GAMEPAD_BUTTON_BACK, SDL_GAMEPAD_BUTTON_GUIDE, SDL_GAMEPAD_BUTTON_START, @@ -142,18 +162,18 @@ typedef enum SDL_GamepadButton SDL_GAMEPAD_BUTTON_DPAD_DOWN, SDL_GAMEPAD_BUTTON_DPAD_LEFT, SDL_GAMEPAD_BUTTON_DPAD_RIGHT, - SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ - SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */ - SDL_GAMEPAD_BUTTON_MISC2, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC3, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC4, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC5, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC6, /* Additional button */ - SDL_GAMEPAD_BUTTON_MAX + SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */ + SDL_GAMEPAD_BUTTON_COUNT } SDL_GamepadButton; /** @@ -165,7 +185,7 @@ typedef enum SDL_GamepadButton * For a complete set, you should look at the button and gamepad type and have * a set of symbols that work well with your art style. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButtonLabel { @@ -192,7 +212,7 @@ typedef enum SDL_GamepadButtonLabel * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the * same range that will be reported by the lower-level SDL_GetJoystickAxis(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadAxis { @@ -203,7 +223,7 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_RIGHTY, SDL_GAMEPAD_AXIS_LEFT_TRIGGER, SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, - SDL_GAMEPAD_AXIS_MAX + SDL_GAMEPAD_AXIS_COUNT } SDL_GamepadAxis; /** @@ -214,7 +234,7 @@ typedef enum SDL_GamepadAxis * gamepad. This enum is used as part of SDL_GamepadBinding to specify those * mappings. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadBindingType { @@ -235,7 +255,7 @@ typedef enum SDL_GamepadBindingType * more with a simple text string. Those strings are parsed into a collection * of these structs to make it easier to operate on the data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetGamepadBindings */ @@ -293,6 +313,9 @@ typedef struct SDL_GamepadBinding * * Buttons can be used as a gamepad axes and vice versa. * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * * This string shows an example of a valid mapping for a gamepad: * * ```c @@ -305,10 +328,15 @@ typedef struct SDL_GamepadBinding * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); @@ -321,6 +349,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -330,21 +361,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * constrained environment. * * \param src the data stream for the mappings to be added. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the number of mappings added or -1 on failure; call SDL_GetError() * for more information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromFile * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ -extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); /** * Load a set of gamepad mappings from a file. @@ -355,6 +389,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -365,12 +402,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); @@ -379,12 +419,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file) * * This will generate gamepad events as needed if device mappings change. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. @@ -396,7 +436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); @@ -408,7 +448,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); * information. This should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUID @@ -425,7 +465,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid); * available; call SDL_GetError() for more information. This should * be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMappingForID @@ -442,26 +482,26 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); * \param instance_id the joystick instance ID. * \param mapping the mapping to use for this device, or NULL to clear the * mapping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMapping */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); /** * Return whether a gamepad is currently connected. * - * \returns SDL_TRUE if a gamepad is connected, SDL_FALSE otherwise. + * \returns true if a gamepad is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. @@ -472,7 +512,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasGamepad * \sa SDL_OpenGamepad @@ -483,15 +523,15 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); * Check if the given joystick is supported by the gamepad interface. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the given joystick is supported by the gamepad - * interface, SDL_FALSE if it isn't or it's an invalid index. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks * \sa SDL_OpenGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); /** * Get the implementation dependent name of a gamepad. @@ -502,7 +542,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); * \returns the name of the selected gamepad. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadName * \sa SDL_GetGamepads @@ -518,7 +558,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID * \returns the path of the selected gamepad. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPath * \sa SDL_GetGamepads @@ -533,7 +573,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepads @@ -549,7 +589,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID in * \returns the GUID of the selected gamepad. If called on an invalid index, * this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString * \sa SDL_GetGamepads @@ -566,7 +606,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID inst * \returns the USB vendor ID of the selected gamepad. If called on an invalid * index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendor * \sa SDL_GetGamepads @@ -583,7 +623,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID inst * \returns the USB product ID of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProduct * \sa SDL_GetGamepads @@ -600,7 +640,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID ins * \returns the product version of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersion * \sa SDL_GetGamepads @@ -615,7 +655,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_Joystic * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadType * \sa SDL_GetGamepads @@ -631,7 +671,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_Joystick * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepads @@ -648,7 +688,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys * \returns the mapping string. Returns NULL if no mapping is available. This * should be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads * \sa SDL_GetGamepadMapping @@ -662,7 +702,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID ins * \returns a gamepad identifier or NULL if an error occurred; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseGamepad * \sa SDL_IsGamepad @@ -677,7 +717,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instanc * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); @@ -687,7 +727,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID in * \param player_index the player index, which different from the instance ID. * \returns the SDL_Gamepad associated with a player index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_SetGamepadPlayerIndex @@ -717,7 +757,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int play * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); @@ -735,7 +775,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa * \returns the instance ID of the specified gamepad on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); @@ -747,7 +787,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad * \returns the implementation dependent name for the gamepad, or NULL if * there is no name or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadNameForID */ @@ -761,7 +801,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad * \returns the implementation dependent path for the gamepad, or NULL if * there is no path or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPathForID */ @@ -774,7 +814,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID */ @@ -787,7 +827,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRealGamepadTypeForID */ @@ -801,7 +841,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad * * \param gamepad the gamepad object to query. * \returns the player index for gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadPlayerIndex */ @@ -813,14 +853,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to adjust. * \param player_index player index to assign to this gamepad, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); /** * Get the USB vendor ID of an opened gamepad, if available. @@ -830,7 +870,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *game * \param gamepad the gamepad object to query. * \returns the USB vendor ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendorForID */ @@ -844,7 +884,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductForID */ @@ -858,7 +898,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersionForID */ @@ -872,7 +912,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gam * \param gamepad the gamepad object to query. * \returns the gamepad firmware version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); @@ -884,7 +924,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga * \param gamepad the gamepad object to query. * \returns the serial number, or NULL if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); @@ -897,7 +937,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamep * \param gamepad the gamepad object to query. * \returns the gamepad handle, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); @@ -909,7 +949,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepa * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); @@ -929,7 +969,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnection * battery. * \returns the current battery state. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); @@ -938,12 +978,12 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad * * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). - * \returns SDL_TRUE if the gamepad has been opened and is currently - * connected, or SDL_FALSE if not. + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** * Get the underlying joystick from a gamepad. @@ -961,7 +1001,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); @@ -973,12 +1013,12 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g * * \param enabled whether to process gamepad events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadEventsEnabled * \sa SDL_UpdateGamepads */ -extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); /** * Query the state of gamepad event processing. @@ -986,14 +1026,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * and check the state of the gamepad when you want gamepad information. * - * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE - * otherwise. + * \returns true if gamepad events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); /** * Get the SDL joystick layer bindings for a gamepad. @@ -1005,7 +1044,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); @@ -1016,7 +1055,7 @@ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gam * enabled. Under such circumstances, it will not be necessary to call this * function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); @@ -1032,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); * \returns the SDL_GamepadType enum corresponding to the input string, or * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForType */ @@ -1046,7 +1085,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeFromString */ @@ -1068,7 +1107,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_Gamepad * \returns the SDL_GamepadAxis enum corresponding to the input string, or * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForAxis */ @@ -1082,7 +1121,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAxisFromString */ @@ -1096,14 +1135,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad * * \param gamepad a gamepad. * \param axis an axis enum value (an SDL_GamepadAxis value). - * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. + * \returns true if the gamepad has this axis, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); /** * Get the current state of an axis control on a gamepad. @@ -1122,7 +1161,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD * \returns axis state (including 0) on success or 0 (also) on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis * \sa SDL_GetGamepadButton @@ -1141,7 +1180,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_ * \returns the SDL_GamepadButton enum corresponding to the input string, or * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForButton */ @@ -1155,7 +1194,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonFromString */ @@ -1169,28 +1208,27 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep * * \param gamepad a gamepad. * \param button a button enum value (an SDL_GamepadButton value). - * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. + * \returns true if the gamepad has this button, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the current state of a button on a gamepad. * * \param gamepad a gamepad. * \param button a button index (one of the SDL_GamepadButton values). - * \returns 1 for pressed state or 0 for not pressed state or failure; call - * SDL_GetError() for more information. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the label of a button on a gamepad. @@ -1199,7 +1237,7 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabel */ @@ -1212,7 +1250,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabelForType */ @@ -1224,7 +1262,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL * \param gamepad a gamepad. * \returns number of touchpads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ @@ -1238,7 +1276,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad) * \param touchpad a touchpad. * \returns number of supported simultaneous fingers. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTouchpadFinger * \sa SDL_GetNumGamepadTouchpads @@ -1251,35 +1289,36 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga * \param gamepad a gamepad. * \param touchpad a touchpad. * \param finger a finger. - * \param state filled with state. - * \param x filled with x position, normalized 0 to 1, with the origin in the - * upper left. - * \param y filled with y position, normalized 0 to 1, with the origin in the - * upper left. - * \param pressure filled with pressure value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); /** * Return whether a gamepad has a particular sensor. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. + * \returns true if the sensor exists, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadSensorData * \sa SDL_GetGamepadSensorDataRate * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Set whether data reporting for a gamepad sensor is enabled. @@ -1287,28 +1326,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, * \param gamepad the gamepad to update. * \param type the type of sensor to enable/disable. * \param enabled whether data reporting should be enabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasSensor * \sa SDL_GamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); /** * Query whether sensor data reporting is enabled for a gamepad. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. + * \returns true if the sensor is enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Get the data rate (number of events per second) of a gamepad sensor. @@ -1317,7 +1356,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep * \param type the type of sensor to query. * \returns the data rate, or 0.0f if the data rate is not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); @@ -1331,12 +1370,12 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game * \param type the type of sensor to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); /** * Start a rumble effect on a gamepad. @@ -1353,12 +1392,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamep * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the gamepad's triggers. @@ -1379,14 +1418,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uin * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a gamepad's LED color. @@ -1401,12 +1440,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *game * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** * Send a gamepad specific effect packet. @@ -1414,12 +1453,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uin * \param gamepad the gamepad to affect. * \param data the data to send to the gamepad. * \param size the size of the data to send to the gamepad. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); /** * Close a gamepad previously opened with SDL_OpenGamepad(). @@ -1427,7 +1466,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenGamepad */ @@ -1441,7 +1480,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); * \param button a button on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis */ @@ -1454,7 +1493,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt * \param axis an axis on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForButton */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h index bba47cc..fa870a5 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,281 @@ /** * # CategoryGPU * - * Include file for SDL GPU API functions + * The GPU API offers a cross-platform way for apps to talk to modern graphics + * hardware. It offers both 3D graphics and compute support, in the style of + * Metal, Vulkan, and Direct3D 12. + * + * A basic workflow might be something like this: + * + * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to + * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you + * can render offscreen entirely, perhaps for image processing, and not use a + * window at all. + * + * Next the app prepares static data (things that are created once and used + * over and over). For example: + * + * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader(). + * - Vertex buffers (arrays of geometry data) and other data rendering will + * need: use SDL_UploadToGPUBuffer(). + * - Textures (images): use SDL_UploadToGPUTexture(). + * - Samplers (how textures should be read from): use SDL_CreateGPUSampler(). + * - Render pipelines (precalculated rendering state): use + * SDL_CreateGPUGraphicsPipeline() + * + * To render, the app creates one or more command buffers, with + * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering + * instructions that will be submitted to the GPU in batch. Complex scenes can + * use multiple command buffers, maybe configured across multiple threads in + * parallel, as long as they are submitted in the correct order, but many apps + * will just need one command buffer per frame. + * + * Rendering can happen to a texture (what other APIs call a "render target") + * or it can happen to the swapchain texture (which is just a special texture + * that represents a window's contents). The app can use + * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. */ #ifndef SDL_gpu_h_ @@ -44,132 +318,394 @@ extern "C" { /* Type Declarations */ +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ typedef struct SDL_GPUFence SDL_GPUFence; +/** + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUPrimitiveType { - SDL_GPU_PRIMITIVETYPE_POINTLIST, - SDL_GPU_PRIMITIVETYPE_LINELIST, - SDL_GPU_PRIMITIVETYPE_LINESTRIP, - SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, - SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ } SDL_GPUPrimitiveType; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPULoadOp { - SDL_GPU_LOADOP_LOAD, - SDL_GPU_LOADOP_CLEAR, - SDL_GPU_LOADOP_DONT_CARE + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ } SDL_GPULoadOp; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPUStoreOp { - SDL_GPU_STOREOP_STORE, - SDL_GPU_STOREOP_DONT_CARE + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ } SDL_GPUStoreOp; +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUIndexElementSize { - SDL_GPU_INDEXELEMENTSIZE_16BIT, - SDL_GPU_INDEXELEMENTSIZE_32BIT + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ } SDL_GPUIndexElementSize; -/* Texture format support varies depending on driver, hardware, and usage flags. - * In general, you should use SDL_GPUTextureSupportsFormat to query if a format - * is supported before using it. However, there are a few guaranteed formats. +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE * * For SAMPLER usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R8G8_SNORM - * - R8G8B8A8_SNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB - * - D16_UNORM + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM * * For COLOR_TARGET usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB * * For STORAGE usages, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - R8G8B8A8_SNORM - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT * - * For DEPTH_STENCIL_TARGET usage, the following formats are universally supported: - * - D16_UNORM - * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT - * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT * - * Unless D16_UNORM is sufficient for your purposes, always check which - * of D24/D32 is supported before creating a depth-stencil texture! + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat */ typedef enum SDL_GPUTextureFormat { - SDL_GPU_TEXTUREFORMAT_INVALID = -1, + SDL_GPU_TEXTUREFORMAT_INVALID, /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, - SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, - SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, - SDL_GPU_TEXTUREFORMAT_R8_UNORM, - SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, /* Compressed Unsigned Normalized Float Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC1_UNORM, - SDL_GPU_TEXTUREFORMAT_BC2_UNORM, - SDL_GPU_TEXTUREFORMAT_BC3_UNORM, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, /* Signed Float Color Formats */ SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, @@ -177,6 +713,8 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, /* Unsigned Integer Color Formats */ SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_UINT, @@ -184,48 +722,153 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, /* SRGB Unsigned Normalized Color Formats */ SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, /* Compressed SRGB Unsigned Normalized Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC3_UNORM_SRGB, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, /* Depth Formats */ SDL_GPU_TEXTUREFORMAT_D16_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D32_FLOAT, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, - SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT } SDL_GPUTextureFormat; -typedef enum SDL_GPUTextureUsageFlagBits -{ - SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT = 0x00000001, - SDL_GPU_TEXTUREUSAGE_COLOR_TARGET_BIT = 0x00000002, - SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET_BIT = 0x00000004, - SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUTextureUsageFlagBits; - +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef Uint32 SDL_GPUTextureUsageFlags; +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef enum SDL_GPUTextureType { - SDL_GPU_TEXTURETYPE_2D, - SDL_GPU_TEXTURETYPE_2D_ARRAY, - SDL_GPU_TEXTURETYPE_3D, - SDL_GPU_TEXTURETYPE_CUBE + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ } SDL_GPUTextureType; +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ typedef enum SDL_GPUSampleCount { - SDL_GPU_SAMPLECOUNT_1, - SDL_GPU_SAMPLECOUNT_2, - SDL_GPU_SAMPLECOUNT_4, - SDL_GPU_SAMPLECOUNT_8 + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ } SDL_GPUSampleCount; + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_GPUCubeMapFace { SDL_GPU_CUBEMAPFACE_POSITIVEX, @@ -236,45 +879,87 @@ typedef enum SDL_GPUCubeMapFace SDL_GPU_CUBEMAPFACE_NEGATIVEZ } SDL_GPUCubeMapFace; -typedef enum SDL_GPUBufferUsageFlagBits -{ - SDL_GPU_BUFFERUSAGE_VERTEX_BIT = 0x00000001, - SDL_GPU_BUFFERUSAGE_INDEX_BIT = 0x00000002, - SDL_GPU_BUFFERUSAGE_INDIRECT_BIT = 0x00000004, - SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUBufferUsageFlagBits; - +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ typedef Uint32 SDL_GPUBufferUsageFlags; +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef enum SDL_GPUTransferBufferUsage { SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD } SDL_GPUTransferBufferUsage; +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef enum SDL_GPUShaderStage { SDL_GPU_SHADERSTAGE_VERTEX, SDL_GPU_SHADERSTAGE_FRAGMENT } SDL_GPUShaderStage; -typedef enum SDL_GPUShaderFormatFlagBits -{ - SDL_GPU_SHADERFORMAT_INVALID = 0x00000000, - SDL_GPU_SHADERFORMAT_SECRET = 0x00000001, /* NDA'd platforms */ - SDL_GPU_SHADERFORMAT_SPIRV = 0x00000002, /* Vulkan */ - SDL_GPU_SHADERFORMAT_DXBC = 0x00000004, /* D3D11 (Shader Model 5_0) */ - SDL_GPU_SHADERFORMAT_DXIL = 0x00000008, /* D3D12 */ - SDL_GPU_SHADERFORMAT_MSL = 0x00000010, /* Metal */ - SDL_GPU_SHADERFORMAT_METALLIB = 0x00000020, /* Metal */ -} SDL_GPUShaderFormatFlagBits; - +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef Uint32 SDL_GPUShaderFormat; +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexElementFormat { + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + /* 32-bit Signed Integers */ SDL_GPU_VERTEXELEMENTFORMAT_INT, SDL_GPU_VERTEXELEMENTFORMAT_INT2, @@ -330,125 +1015,230 @@ typedef enum SDL_GPUVertexElementFormat SDL_GPU_VERTEXELEMENTFORMAT_HALF4 } SDL_GPUVertexElementFormat; +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexInputRate { - SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, - SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ } SDL_GPUVertexInputRate; +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFillMode { - SDL_GPU_FILLMODE_FILL, - SDL_GPU_FILLMODE_LINE + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ } SDL_GPUFillMode; +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCullMode { - SDL_GPU_CULLMODE_NONE, - SDL_GPU_CULLMODE_FRONT, - SDL_GPU_CULLMODE_BACK + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ } SDL_GPUCullMode; +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFrontFace { - SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, - SDL_GPU_FRONTFACE_CLOCKWISE + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ } SDL_GPUFrontFace; +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCompareOp { - SDL_GPU_COMPAREOP_NEVER, - SDL_GPU_COMPAREOP_LESS, - SDL_GPU_COMPAREOP_EQUAL, - SDL_GPU_COMPAREOP_LESS_OR_EQUAL, - SDL_GPU_COMPAREOP_GREATER, - SDL_GPU_COMPAREOP_NOT_EQUAL, - SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, - SDL_GPU_COMPAREOP_ALWAYS + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ } SDL_GPUCompareOp; +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUStencilOp { - SDL_GPU_STENCILOP_KEEP, - SDL_GPU_STENCILOP_ZERO, - SDL_GPU_STENCILOP_REPLACE, - SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_INVERT, - SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, - SDL_GPU_STENCILOP_DECREMENT_AND_WRAP + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ } SDL_GPUStencilOp; +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendOp { - SDL_GPU_BLENDOP_ADD, - SDL_GPU_BLENDOP_SUBTRACT, - SDL_GPU_BLENDOP_REVERSE_SUBTRACT, - SDL_GPU_BLENDOP_MIN, - SDL_GPU_BLENDOP_MAX + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ } SDL_GPUBlendOp; +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendFactor { - SDL_GPU_BLENDFACTOR_ZERO, - SDL_GPU_BLENDFACTOR_ONE, - SDL_GPU_BLENDFACTOR_SRC_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, - SDL_GPU_BLENDFACTOR_DST_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_DST_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, - SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ } SDL_GPUBlendFactor; -typedef enum SDL_GPUColorComponentFlagBits -{ - SDL_GPU_COLORCOMPONENT_R_BIT = 0x00000001, - SDL_GPU_COLORCOMPONENT_G_BIT = 0x00000002, - SDL_GPU_COLORCOMPONENT_B_BIT = 0x00000004, - SDL_GPU_COLORCOMPONENT_A_BIT = 0x00000008 -} SDL_GPUColorComponentFlagBits; - +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef Uint8 SDL_GPUColorComponentFlags; +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUFilter { - SDL_GPU_FILTER_NEAREST, - SDL_GPU_FILTER_LINEAR + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ } SDL_GPUFilter; +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerMipmapMode { - SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, - SDL_GPU_SAMPLERMIPMAPMODE_LINEAR + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ } SDL_GPUSamplerMipmapMode; +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerAddressMode { - SDL_GPU_SAMPLERADDRESSMODE_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ } SDL_GPUSamplerAddressMode; -/* - * VSYNC: - * Waits for vblank before presenting. - * If there is a pending image to present, the new image is enqueued for presentation. - * Disallows tearing at the cost of visual latency. - * When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight. - * IMMEDIATE: - * Immediately presents. - * Lowest latency option, but tearing may occur. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. - * MAILBOX: - * Waits for vblank before presenting. No tearing is possible. - * If there is a pending image to present, the pending image is replaced by the new image. - * Similar to VSYNC, but with reduced visual latency. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUPresentMode { @@ -457,493 +1247,866 @@ typedef enum SDL_GPUPresentMode SDL_GPU_PRESENTMODE_MAILBOX } SDL_GPUPresentMode; -/* - * SDR: - * B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. Blends raw pixel values. - * SDR_LINEAR: - * B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. Blends in linear space. - * HDR_EXTENDED_LINEAR: - * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. Blends in linear space. - * HDR10_ST2048: - * A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding. Blends raw pixel values. (TODO: verify this) +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUSwapchainComposition { SDL_GPU_SWAPCHAINCOMPOSITION_SDR, SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, - SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 } SDL_GPUSwapchainComposition; -typedef enum SDL_GPUDriver -{ - SDL_GPU_DRIVER_INVALID = -1, - SDL_GPU_DRIVER_SECRET, /* NDA'd platforms */ - SDL_GPU_DRIVER_VULKAN, - SDL_GPU_DRIVER_D3D11, - SDL_GPU_DRIVER_D3D12, - SDL_GPU_DRIVER_METAL -} SDL_GPUDriver; - /* Structures */ -typedef struct SDL_GPUDepthStencilValue -{ - float depth; - Uint8 stencil; -} SDL_GPUDepthStencilValue; - +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ typedef struct SDL_GPUViewport { - float x; - float y; - float w; - float h; - float minDepth; - float maxDepth; + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ } SDL_GPUViewport; +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureTransferInfo { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; /* starting location of the image data */ - Uint32 imagePitch; /* number of pixels from one row to the next */ - Uint32 imageHeight; /* number of rows from one layer/depth-slice to the next */ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ } SDL_GPUTextureTransferInfo; +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUTransferBufferLocation { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ } SDL_GPUTransferBufferLocation; +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + */ typedef struct SDL_GPUTextureLocation { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ } SDL_GPUTextureLocation; +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; - Uint32 w; - Uint32 h; - Uint32 d; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ } SDL_GPUTextureRegion; +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ typedef struct SDL_GPUBlitRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; - Uint32 x; - Uint32 y; - Uint32 w; - Uint32 h; + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ } SDL_GPUBlitRegion; +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + */ typedef struct SDL_GPUBufferLocation { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ } SDL_GPUBufferLocation; +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUBufferRegion { - SDL_GPUBuffer *buffer; - Uint32 offset; - Uint32 size; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ } SDL_GPUBufferRegion; -/* Note that the `firstVertex` and `firstInstance` parameters are NOT compatible with - * built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If - * your shader depends on these variables, the correlating draw call parameter MUST - * be 0. +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect */ typedef struct SDL_GPUIndirectDrawCommand { - Uint32 vertexCount; /* number of vertices to draw */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstVertex; /* index of the first vertex to draw */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ typedef struct SDL_GPUIndexedIndirectDrawCommand { - Uint32 indexCount; /* number of vertices to draw per instance */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstIndex; /* base index within the index buffer */ - Sint32 vertexOffset; /* value added to vertex index before indexing into the vertex buffer */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndexedIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ typedef struct SDL_GPUIndirectDispatchCommand { - Uint32 groupCountX; - Uint32 groupCountY; - Uint32 groupCountZ; + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ } SDL_GPUIndirectDispatchCommand; /* State structures */ +/** + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef struct SDL_GPUSamplerCreateInfo { - SDL_GPUFilter minFilter; - SDL_GPUFilter magFilter; - SDL_GPUSamplerMipmapMode mipmapMode; - SDL_GPUSamplerAddressMode addressModeU; - SDL_GPUSamplerAddressMode addressModeV; - SDL_GPUSamplerAddressMode addressModeW; - float mipLodBias; - SDL_bool anisotropyEnable; - float maxAnisotropy; - SDL_bool compareEnable; - SDL_GPUCompareOp compareOp; - float minLod; - float maxLod; + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUSamplerCreateInfo; -typedef struct SDL_GPUVertexBinding +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexBufferDescription { - Uint32 binding; - Uint32 stride; - SDL_GPUVertexInputRate inputRate; - Uint32 instanceStepRate; /* ignored unless inputRate is INSTANCE */ -} SDL_GPUVertexBinding; + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */ +} SDL_GPUVertexBufferDescription; +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + */ typedef struct SDL_GPUVertexAttribute { - Uint32 location; - Uint32 binding; - SDL_GPUVertexElementFormat format; - Uint32 offset; + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ } SDL_GPUVertexAttribute; +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + */ typedef struct SDL_GPUVertexInputState { - const SDL_GPUVertexBinding *vertexBindings; - Uint32 vertexBindingCount; - const SDL_GPUVertexAttribute *vertexAttributes; - Uint32 vertexAttributeCount; + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ } SDL_GPUVertexInputState; +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ typedef struct SDL_GPUStencilOpState { - SDL_GPUStencilOp failOp; - SDL_GPUStencilOp passOp; - SDL_GPUStencilOp depthFailOp; - SDL_GPUCompareOp compareOp; + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ } SDL_GPUStencilOpState; -typedef struct SDL_GPUColorAttachmentBlendState +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState { - SDL_bool blendEnable; - SDL_GPUBlendFactor srcColorBlendFactor; - SDL_GPUBlendFactor dstColorBlendFactor; - SDL_GPUBlendOp colorBlendOp; - SDL_GPUBlendFactor srcAlphaBlendFactor; - SDL_GPUBlendFactor dstAlphaBlendFactor; - SDL_GPUBlendOp alphaBlendOp; - SDL_GPUColorComponentFlags colorWriteMask; -} SDL_GPUColorAttachmentBlendState; + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef struct SDL_GPUShaderCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - SDL_GPUShaderStage stage; - Uint32 samplerCount; - Uint32 storageTextureCount; - Uint32 storageBufferCount; - Uint32 uniformBufferCount; + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUShaderCreateInfo; +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + */ typedef struct SDL_GPUTextureCreateInfo { - SDL_GPUTextureType type; - SDL_GPUTextureFormat format; - SDL_GPUTextureUsageFlags usageFlags; - Uint32 width; - Uint32 height; - Uint32 layerCountOrDepth; - Uint32 levelCount; - SDL_GPUSampleCount sampleCount; + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTextureCreateInfo; -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" - +/** + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + */ typedef struct SDL_GPUBufferCreateInfo { - SDL_GPUBufferUsageFlags usageFlags; - Uint32 sizeInBytes; + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUBufferCreateInfo; +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef struct SDL_GPUTransferBufferCreateInfo { - SDL_GPUTransferBufferUsage usage; - Uint32 sizeInBytes; + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTransferBufferCreateInfo; /* Pipeline state structures */ +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if + * enable_depth_clip is true. If you rely on this clamp+clip behavior, + * consider enabling depth clip and then manually clamping depth in your + * fragment shaders on Metal and Vulkan. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPURasterizerState { - SDL_GPUFillMode fillMode; - SDL_GPUCullMode cullMode; - SDL_GPUFrontFace frontFace; - SDL_bool depthBiasEnable; - float depthBiasConstantFactor; - float depthBiasClamp; - float depthBiasSlopeFactor; + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; } SDL_GPURasterizerState; +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUMultisampleState { - SDL_GPUSampleCount sampleCount; - Uint32 sampleMask; + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */ + bool enable_mask; /**< Enables sample masking. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUMultisampleState; +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUDepthStencilState { - SDL_bool depthTestEnable; - SDL_bool depthWriteEnable; - SDL_GPUCompareOp compareOp; - SDL_bool stencilTestEnable; - SDL_GPUStencilOpState backStencilState; - SDL_GPUStencilOpState frontStencilState; - Uint8 compareMask; - Uint8 writeMask; - Uint8 reference; + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUDepthStencilState; -typedef struct SDL_GPUColorAttachmentDescription +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription { - SDL_GPUTextureFormat format; - SDL_GPUColorAttachmentBlendState blendState; -} SDL_GPUColorAttachmentDescription; + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; -typedef struct SDL_GPUGraphicsPipelineAttachmentInfo +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo { - SDL_GPUColorAttachmentDescription *colorAttachmentDescriptions; - Uint32 colorAttachmentCount; - SDL_bool hasDepthStencilAttachment; - SDL_GPUTextureFormat depthStencilFormat; -} SDL_GPUGraphicsPipelineAttachmentInfo; + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ typedef struct SDL_GPUGraphicsPipelineCreateInfo { - SDL_GPUShader *vertexShader; - SDL_GPUShader *fragmentShader; - SDL_GPUVertexInputState vertexInputState; - SDL_GPUPrimitiveType primitiveType; - SDL_GPURasterizerState rasterizerState; - SDL_GPUMultisampleState multisampleState; - SDL_GPUDepthStencilState depthStencilState; - SDL_GPUGraphicsPipelineAttachmentInfo attachmentInfo; - float blendConstants[4]; + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUGraphicsPipelineCreateInfo; +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + */ typedef struct SDL_GPUComputePipelineCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - Uint32 readOnlyStorageTextureCount; - Uint32 readOnlyStorageBufferCount; - Uint32 writeOnlyStorageTextureCount; - Uint32 writeOnlyStorageBufferCount; - Uint32 uniformBufferCount; - Uint32 threadCountX; - Uint32 threadCountY; - Uint32 threadCountZ; + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUComputePipelineCreateInfo; -typedef struct SDL_GPUColorAttachmentInfo +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo { - /* The texture that will be used as a color attachment by a render pass. */ - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; /* For 3D textures, you can bind an individual depth plane as an attachment. */ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; - /* Can be ignored by RenderPass if CLEAR is not used */ - SDL_FColor clearColor; - - /* Determines what is done with the texture at the beginning of the render pass. - * - * LOAD: - * Loads the data currently in the texture. - * - * CLEAR: - * Clears the texture to a single color. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the texture at the end of the render pass. - * - * STORE: - * Stores the results of the render pass in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and loadOp is not LOAD */ - SDL_bool cycle; -} SDL_GPUColorAttachmentInfo; - -typedef struct SDL_GPUDepthStencilAttachmentInfo +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo { - /* The texture that will be used as the depth stencil attachment by a render pass. */ - SDL_GPUTexture *texture; + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; - /* Can be ignored by the render pass if CLEAR is not used */ - SDL_GPUDepthStencilValue depthStencilClearValue; - - /* Determines what is done with the depth values at the beginning of the render pass. - * - * LOAD: - * Loads the depth values currently in the texture. - * - * CLEAR: - * Clears the texture to a single depth. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the depth values at the end of the render pass. - * - * STORE: - * Stores the depth results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* Determines what is done with the stencil values at the beginning of the render pass. - * - * LOAD: - * Loads the stencil values currently in the texture. - * - * CLEAR: - * Clears the texture to a single stencil value. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp stencilLoadOp; - - /* Determines what is done with the stencil values at the end of the render pass. - * - * STORE: - * Stores the stencil results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp stencilStoreOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and any load ops are not LOAD */ - SDL_bool cycle; -} SDL_GPUDepthStencilAttachmentInfo; +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; /* Binding structs */ +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + */ typedef struct SDL_GPUBufferBinding { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ } SDL_GPUBufferBinding; +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ typedef struct SDL_GPUTextureSamplerBinding { - SDL_GPUTexture *texture; - SDL_GPUSampler *sampler; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ } SDL_GPUTextureSamplerBinding; -typedef struct SDL_GPUStorageBufferWriteOnlyBinding +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding { - SDL_GPUBuffer *buffer; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; - /* if SDL_TRUE, cycles the buffer if it is bound. */ - SDL_bool cycle; -} SDL_GPUStorageBufferWriteOnlyBinding; - -typedef struct SDL_GPUStorageTextureWriteOnlyBinding +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - - /* if SDL_TRUE, cycles the texture if the texture is bound. */ - SDL_bool cycle; -} SDL_GPUStorageTextureWriteOnlyBinding; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; /* Functions */ /* Device */ /** - * Creates a GPU context. + * Checks for GPU runtime support. * - * \param formatFlags a bitflag indicating which shader formats the app is - * able to provide. - * \param debugMode enable debug mode properties and validations. + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. * \param name the preferred GPU driver, or NULL to let SDL pick the optimal * driver. - * \returns a GPU context on success or NULL on failure. + * \returns true if supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( - SDL_GPUShaderFormat formatFlags, - SDL_bool debugMode, + SDL_GPUShaderFormat format_flags, + bool debug_mode, const char *name); /** @@ -951,26 +2114,26 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * * These are the supported properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL`: enable debug mode properties - * and validations, defaults to SDL_TRUE. - * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL`: enable to prefer energy - * efficiency over maximum GPU performance, defaults to SDL_FALSE. + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to * use, if a specific one is desired. * * These are the current shader format properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to * provide shaders for an NDA platform. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to * provide SPIR-V shaders if applicable. - * - SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL`: The app is able to provide - * DXBC shaders if applicable - * `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to * provide DXIL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL`: The app is able to provide - * MSL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to * provide Metal shader libraries if applicable. * * With the D3D12 renderer: @@ -979,25 +2142,28 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * use for all vertex semantics, default is "TEXCOORD". * * \param props the properties to use. - * \returns a GPU context on success or NULL on failure. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( SDL_PropertiesID props); -#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" -#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL "SDL.gpu.device.create.shaders.secret" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" /** @@ -1005,70 +2171,132 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( * * \param device a GPU Context to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUDevice */ extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); /** - * Returns the backend used to create this GPU context. + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. * * \param device a GPU context to query. - * \returns an SDL_GPUDriver value, or SDL_GPU_DRIVER_INVALID on error. + * \returns the name of the device's driver, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); /* State Creation */ /** * Creates a pipeline object to be used in a compute workflow. * - * Shader resource bindings must be authored to follow a particular order. For - * SPIR-V shaders, use the following resource sets: 0: Read-only storage - * textures, followed by read-only storage buffers 1: Write-only storage - * textures, followed by write-only storage buffers 2: Uniform buffers + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Read-only storage textures, followed by read-only storage - * buffers For u registers: Write-only storage textures, followed by - * write-only storage buffers For b registers: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXIL shaders, use the following register order: (t[n], space0): - * Read-only storage textures, followed by read-only storage buffers (u[n], - * space1): Write-only storage textures, followed by write-only storage - * buffers (b[n], space2): Uniform buffers + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers * - * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, - * followed by write-only storage buffers, followed by write-only storage - * buffers For [[texture]]: Read-only storage textures, followed by write-only - * storage textures + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. * * \param device a GPU Context. - * \param computePipelineCreateInfo a struct describing the state of the - * requested compute pipeline. - * \returns a compute pipeline object on success, or NULL on failure. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUComputePipeline * \sa SDL_ReleaseGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipelineCreateInfo *computePipelineCreateInfo); + const SDL_GPUComputePipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" /** * Creates a pipeline object to be used in a graphics workflow. * - * \param device a GPU Context. - * \param pipelineCreateInfo a struct describing the state of the desired - * graphics pipeline. - * \returns a graphics pipeline object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUShader * \sa SDL_BindGPUGraphicsPipeline @@ -1076,26 +2304,36 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipelineCreateInfo *pipelineCreateInfo); + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" /** * Creates a sampler object to be used when binding textures in a graphics * workflow. * - * \param device a GPU Context. - * \param samplerCreateInfo a struct describing the state of the desired - * sampler. - * \returns a sampler object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUVertexSamplers * \sa SDL_BindGPUFragmentSamplers - * \sa SDL_ReleaseSampler + * \sa SDL_ReleaseGPUSampler */ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( SDL_GPUDevice *device, - SDL_GPUSamplerCreateInfo *samplerCreateInfo); + const SDL_GPUSamplerCreateInfo *createinfo); + +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" /** * Creates a shader to be used when creating a graphics pipeline. @@ -1103,46 +2341,78 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * Shader resource bindings must be authored to follow a particular order * depending on the shader format. * - * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: - * Sampled textures, followed by storage textures, followed by storage buffers - * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by - * storage textures, followed by storage buffers 3: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Sampled textures, followed by storage textures, followed by - * storage buffers For s registers: Samplers with indices corresponding to the - * sampled textures For b registers: Uniform buffers + * For vertex shaders: * - * For DXIL shaders, use the following register order: For vertex shaders: - * (t[n], space0): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space0): Samplers with indices corresponding to the - * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n], - * space2): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space2): Samplers with indices corresponding to the - * sampled textures (b[n], space3): Uniform buffers + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers * - * For MSL/metallib, use the following order: For [[texture]]: Sampled - * textures, followed by storage textures For [[sampler]]: Samplers with - * indices corresponding to the sampled textures For [[buffer]]: Uniform - * buffers, followed by storage buffers. Vertex buffer 0 is bound at - * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than - * manually authoring vertex buffer indices, use the [[stage_in]] attribute - * which will automatically use the vertex input information from the - * SDL_GPUPipeline. + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. * * \param device a GPU Context. - * \param shaderCreateInfo a struct describing the state of the desired - * shader. - * \returns a shader object on success, or NULL on failure. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUGraphicsPipeline * \sa SDL_ReleaseGPUShader */ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( SDL_GPUDevice *device, - SDL_GPUShaderCreateInfo *shaderCreateInfo); + const SDL_GPUShaderCreateInfo *createinfo); + +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" /** * Creates a texture object to be used in graphics or compute workflows. @@ -1157,12 +2427,36 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * - * \param device a GPU Context. - * \param textureCreateInfo a struct describing the state of the texture to - * create. - * \returns a texture object on success, or NULL on failure. + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the texture to create. + * \returns a texture object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture * \sa SDL_DownloadFromGPUTexture @@ -1177,7 +2471,15 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( */ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, - SDL_GPUTextureCreateInfo *textureCreateInfo); + const SDL_GPUTextureCreateInfo *createinfo); + +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" /** * Creates a buffer object to be used in graphics or compute workflows. @@ -1188,35 +2490,63 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * Note that certain combinations of usage flags are invalid. For example, a * buffer cannot have both the VERTEX and INDEX flags. * - * \param device a GPU Context. - * \param bufferCreateInfo a struct describing the state of the buffer to - * create. - * \returns a buffer object on success, or NULL on failure. + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer * \sa SDL_BindGPUVertexBuffers * \sa SDL_BindGPUIndexBuffer * \sa SDL_BindGPUVertexStorageBuffers * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect * \sa SDL_ReleaseGPUBuffer */ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( SDL_GPUDevice *device, - SDL_GPUBufferCreateInfo *bufferCreateInfo); + const SDL_GPUBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" /** * Creates a transfer buffer to be used when uploading to or downloading from * graphics resources. * - * \param device a GPU Context. - * \param transferBufferCreateInfo a struct describing the state of the - * transfer buffer to create. - * \returns a transfer buffer on success, or NULL on failure. + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer @@ -1226,20 +2556,28 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( */ extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBufferCreateInfo *transferBufferCreateInfo); + const SDL_GPUTransferBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" /* Debug Naming */ /** * Sets an arbitrary string constant to label a buffer. * - * Useful for debugging. + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. * * \param device a GPU Context. * \param buffer a buffer to attach the name to. * \param text a UTF-8 string constant to mark as the name of the buffer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( SDL_GPUDevice *device, @@ -1249,13 +2587,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( /** * Sets an arbitrary string constant to label a texture. * - * Useful for debugging. + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. * * \param device a GPU Context. * \param texture a texture to attach the name to. * \param text a UTF-8 string constant to mark as the name of the texture. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( SDL_GPUDevice *device, @@ -1267,13 +2612,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( * * Useful for debugging. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param text a UTF-8 string constant to insert as the label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *text); /** @@ -1290,28 +2635,28 @@ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( * pass rather than the command buffer. For best results, if you push a debug * group during a pass, always pop it in the same pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param name a UTF-8 string constant that names the group. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PopGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *name); /** * Ends the most-recently pushed debug group. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /* Disposal */ @@ -1323,7 +2668,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( * \param device a GPU context. * \param texture a texture to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( SDL_GPUDevice *device, @@ -1332,12 +2677,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( /** * Frees the given sampler as soon as it is safe to do so. * - * You must not reference the texture after calling this function. + * You must not reference the sampler after calling this function. * * \param device a GPU context. * \param sampler a sampler to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( SDL_GPUDevice *device, @@ -1351,7 +2696,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( * \param device a GPU context. * \param buffer a buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( SDL_GPUDevice *device, @@ -1363,13 +2708,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( * You must not reference the transfer buffer after calling this function. * * \param device a GPU context. - * \param transferBuffer a transfer buffer to be destroyed. + * \param transfer_buffer a transfer buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /** * Frees the given compute pipeline as soon as it is safe to do so. @@ -1377,13 +2722,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( * You must not reference the compute pipeline after calling this function. * * \param device a GPU context. - * \param computePipeline a compute pipeline to be destroyed. + * \param compute_pipeline a compute pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePipeline *compute_pipeline); /** * Frees the given shader as soon as it is safe to do so. @@ -1393,7 +2738,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( * \param device a GPU context. * \param shader a shader to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( SDL_GPUDevice *device, @@ -1405,29 +2750,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( * You must not reference the graphics pipeline after calling this function. * * \param device a GPU context. - * \param graphicsPipeline a graphics pipeline to be destroyed. + * \param graphics_pipeline a graphics pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipeline *graphicsPipeline); - -/* - * COMMAND BUFFERS - * - * Render state is managed via command buffers. - * When setting render state, that state is always local to the command buffer. - * - * Commands only begin execution on the GPU once Submit is called. - * Once the command buffer is submitted, it is no longer valid to use it. - * - * Command buffers are executed in submission order. If you submit command buffer A and then command buffer B - * all commands in A will begin executing before any command in B begins executing. - * - * In multi-threading scenarios, you should acquire and submit a command buffer on the same thread. - * As long as you satisfy this requirement, all functionality related to command buffers is thread-safe. - */ + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Acquire a command buffer. @@ -1437,10 +2766,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( * acquired on. The command buffer should be submitted on the thread it was * acquired on. * - * \param device a GPU context. - * \returns a command buffer. + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. * - * \since This function is available since SDL 3.0.0. + * \param device a GPU context. + * \returns a command buffer, or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence @@ -1448,118 +2785,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer( SDL_GPUDevice *device); -/* - * UNIFORM DATA - * - * Uniforms are for passing data to shaders. - * The uniform data will be constant across all executions of the shader. - * - * There are 4 available uniform slots per shader stage (vertex, fragment, compute). - * Uniform data pushed to a slot on a stage keeps its value throughout the command buffer - * until you call the relevant Push function on that slot again. - * - * For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, - * push the camera matrix at the start of the command buffer, and that data will be used for every - * subsequent draw call. - * - * It is valid to push uniform data during a render or compute pass. - * - * Uniforms are best for pushing small amounts of data. - * If you are pushing more than a matrix or two per call you should consider using a storage buffer instead. - */ +/* Uniform Data */ /** * Pushes data to a vertex uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the vertex uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the vertex uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a fragment uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the fragment uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the fragment uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); - -/* - * A NOTE ON CYCLING - * - * When using a command buffer, operations do not occur immediately - - * they occur some time after the command buffer is submitted. - * - * When a resource is used in a pending or active command buffer, it is considered to be "bound". - * When a resource is no longer used in any pending or active command buffers, it is considered to be "unbound". - * - * If data resources are bound, it is unspecified when that data will be unbound - * unless you acquire a fence when submitting the command buffer and wait on it. - * However, this doesn't mean you need to track resource usage manually. - * - * All of the functions and structs that involve writing to a resource have a "cycle" bool. - * GPUTransferBuffer, GPUBuffer, and GPUTexture all effectively function as ring buffers on internal resources. - * When cycle is SDL_TRUE, if the resource is bound, the cycle rotates to the next unbound internal resource, - * or if none are available, a new one is created. - * This means you don't have to worry about complex state tracking and synchronization as long as cycling is correctly employed. - * - * For example: you can call MapTransferBuffer, write texture data, UnmapTransferBuffer, and then UploadToTexture. - * The next time you write texture data to the transfer buffer, if you set the cycle param to SDL_TRUE, you don't have - * to worry about overwriting any data that is not yet uploaded. - * - * Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. - * If you set cycle to SDL_TRUE in the ColorAttachmentInfo struct, you can prevent this data dependency. - * - * Cycling will never undefine already bound data. - * When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. - * You must take care not to read undefined data. - * - * Note that when cycling a texture, the entire texture will be cycled, - * even if only part of the texture is used in the call, - * so you must consider the entire texture to contain undefined data after cycling. - * - * You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. - * It is OK to overwrite unreferenced data in a bound resource without cycling, - * but overwriting a section of data that has already been referenced will produce unexpected results. - */ + Uint32 length); /* Graphics State */ @@ -1574,212 +2854,240 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( * is called. You cannot begin another render pass, or begin a compute pass or * copy pass until you have ended the render pass. * - * \param commandBuffer a command buffer. - * \param colorAttachmentInfos an array of texture subresources with - * corresponding clear values and load/store ops. - * \param colorAttachmentCount the number of color attachments in the - * colorAttachmentInfos array. - * \param depthStencilAttachmentInfo a texture subresource with corresponding - * clear value and load/store ops, may be - * NULL. + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. * \returns a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPURenderPass */ extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUColorAttachmentInfo *colorAttachmentInfos, - Uint32 colorAttachmentCount, - SDL_GPUDepthStencilAttachmentInfo *depthStencilAttachmentInfo); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); /** * Binds a graphics pipeline on a render pass to be used in rendering. * * A graphics pipeline must be bound before making any draw calls. * - * \param renderPass a render pass handle. - * \param graphicsPipeline the graphics pipeline to bind. + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( - SDL_GPURenderPass *renderPass, - SDL_GPUGraphicsPipeline *graphicsPipeline); + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Sets the current viewport state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param viewport the viewport to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( - SDL_GPURenderPass *renderPass, - SDL_GPUViewport *viewport); + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); /** * Sets the current scissor state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param scissor the scissor area to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( - SDL_GPURenderPass *renderPass, - SDL_Rect *scissor); + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); /** * Binds vertex buffers on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param firstBinding the starting bind point for the vertex buffers. - * \param pBindings an array of SDL_GPUBufferBinding structs containing vertex - * buffers and offset values. - * \param bindingCount the number of bindings in the pBindings array. + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstBinding, - SDL_GPUBufferBinding *pBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); /** * Binds an index buffer on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param pBinding a pointer to a struct containing an index buffer and - * offset. - * \param indexElementSize whether the index values in the buffer are 16- or - * 32-bit. + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( - SDL_GPURenderPass *renderPass, - SDL_GPUBufferBinding *pBinding, - SDL_GPUIndexElementSize indexElementSize); + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); /** * Binds texture-sampler pairs for use on the vertex shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the vertex sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the vertex shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage texture to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage texture to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the vertex shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage buffer slot to begin binding from. - * \param storageBuffers an array of buffers. - * \param bindingCount the number of buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage buffer slot to begin binding from. + * \param storage_buffers an array of buffers. + * \param num_bindings the number of buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Binds texture-sampler pairs for use on the fragment shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the fragment sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the fragment shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the fragment shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffers. - * \param bindingCount the number of storage buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffers. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /* Drawing */ @@ -1789,100 +3097,101 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param indexCount the number of vertices to draw per instance. - * \param instanceCount the number of instances to draw. - * \param firstIndex the starting index within the index buffer. - * \param vertexOffset value added to vertex index before indexing into the - * vertex buffer. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 indexCount, - Uint32 instanceCount, - Uint32 firstIndex, - Sint32 vertexOffset, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); /** * Draws data using bound graphics state. * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param vertexCount the number of vertices to draw. - * \param instanceCount the number of instances that will be drawn. - * \param firstVertex the index of the first vertex to draw. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 vertexCount, - Uint32 instanceCount, - Uint32 firstVertex, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); /** * Draws data using bound graphics state and with draw parameters set from a * buffer. * - * The buffer layout should match the layout of SDL_GPUIndirectDrawCommand. - * You must not call this function before binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Draws data using bound graphics state with an index buffer enabled and with * draw parameters set from a buffer. * - * The buffer layout should match the layout of - * SDL_GPUIndexedIndirectDrawCommand. You must not call this function before - * binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Ends the given render pass. @@ -1890,12 +3199,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( * All bound graphics state on the render pass command buffer is unset. The * render pass handle is now invalid. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( - SDL_GPURenderPass *renderPass); + SDL_GPURenderPass *render_pass); /* Compute Pass */ @@ -1903,89 +3212,115 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( * Begins a compute pass on a command buffer. * * A compute pass is defined by a set of texture subresources and buffers that - * will be written to by compute pipelines. These textures and buffers must - * have been created with the COMPUTE_STORAGE_WRITE bit. All operations - * related to compute pipelines must take place inside of a compute pass. You - * must not begin another compute pass, or a render pass or copy pass before - * ending the compute pass. + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. * - * A VERY IMPORTANT NOTE Textures and buffers bound as write-only MUST NOT be - * read from during the compute pass. Doing so will result in undefined - * behavior. If your compute work requires reading the output from a previous - * dispatch, you MUST end the current compute pass and begin a new one before - * you can safely access the data. + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! * - * \param commandBuffer a command buffer. - * \param storageTextureBindings an array of writeable storage texture binding - * structs. - * \param storageTextureBindingCount the number of storage textures to bind - * from the array. - * \param storageBufferBindings an array of writeable storage buffer binding - * structs. - * \param storageBufferBindingCount the number of storage buffers to bind from - * the array. + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. * \returns a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPUComputePass */ extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUStorageTextureWriteOnlyBinding *storageTextureBindings, - Uint32 storageTextureBindingCount, - SDL_GPUStorageBufferWriteOnlyBinding *storageBufferBindings, - Uint32 storageBufferBindingCount); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); /** * Binds a compute pipeline on a command buffer for use in compute dispatch. * - * \param computePass a compute pass handle. - * \param computePipeline a compute pipeline to bind. + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( - SDL_GPUComputePass *computePass, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler bindings to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures as readonly for use on the compute pipeline. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers as readonly for use on the compute pipeline. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffer binding structs. - * \param bindingCount the number of storage buffers to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffer binding structs. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Dispatches compute work. @@ -1997,21 +3332,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. - * \param groupCountX number of local workgroups to dispatch in the X - * dimension. - * \param groupCountY number of local workgroups to dispatch in the Y - * dimension. - * \param groupCountZ number of local workgroups to dispatch in the Z - * dimension. + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( - SDL_GPUComputePass *computePass, - Uint32 groupCountX, - Uint32 groupCountY, - Uint32 groupCountZ); + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); /** * Dispatches compute work with parameters set from a buffer. @@ -2025,16 +3360,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * \param buffer a buffer containing dispatch parameters. - * \param offsetInBytes the offset to start reading from the dispatch buffer. + * \param offset the offset to start reading from the dispatch buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( - SDL_GPUComputePass *computePass, + SDL_GPUComputePass *compute_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes); + Uint32 offset); /** * Ends the current compute pass. @@ -2042,12 +3377,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( * All bound compute state on the command buffer is unset. The compute pass * handle is now invalid. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( - SDL_GPUComputePass *computePass); + SDL_GPUComputePass *compute_pass); /* TransferBuffer Data */ @@ -2057,28 +3392,29 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( * You must unmap the transfer buffer before encoding upload commands. * * \param device a GPU context. - * \param transferBuffer a transfer buffer. - * \param cycle if SDL_TRUE, cycles the transfer buffer if it is bound. - * \returns the address of the mapped transfer buffer memory. + * \param transfer_buffer a transfer buffer. + * \param cycle if true, cycles the transfer buffer if it is already bound. + * \returns the address of the mapped transfer buffer memory, or NULL on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer, - SDL_bool cycle); + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); /** * Unmaps a previously mapped transfer buffer. * * \param device a GPU context. - * \param transferBuffer a previously mapped transfer buffer. + * \param transfer_buffer a previously mapped transfer buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /* Copy Pass */ @@ -2089,13 +3425,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( * inside a copy pass. You must not begin another copy pass, or a render pass * or compute pass before ending the copy pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \returns a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /** * Uploads data from a transfer buffer to a texture. @@ -2106,21 +3442,19 @@ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( * You must align the data in the transfer buffer to a multiple of the texel * size of the texture format. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with image layout information. * \param destination the destination texture region. - * \param cycle if SDL_TRUE, cycles the texture if the texture is bound, - * otherwise overwrites the data. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureTransferInfo *source, - SDL_GPUTextureRegion *destination, - SDL_bool cycle); - -/* Uploads data from a TransferBuffer to a Buffer. */ + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); /** * Uploads data from a transfer buffer to a buffer. @@ -2128,19 +3462,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( * The upload occurs on the GPU timeline. You may assume that the upload has * finished in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with offset. * \param destination the destination buffer with offset and size. - * \param cycle if SDL_TRUE, cycles the buffer if it is bound, otherwise + * \param cycle if true, cycles the buffer if it is already bound, otherwise * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUTransferBufferLocation *source, - SDL_GPUBufferRegion *destination, - SDL_bool cycle); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); /** * Performs a texture-to-texture copy. @@ -2148,27 +3482,25 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source a source texture region. * \param destination a destination texture region. * \param w the width of the region to copy. * \param h the height of the region to copy. * \param d the depth of the region to copy. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination + * \param cycle if true, cycles the destination texture if the destination * texture is bound, otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureLocation *source, - SDL_GPUTextureLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, Uint32 w, Uint32 h, Uint32 d, - SDL_bool cycle); - -/* Copies data from a buffer to a buffer. */ + bool cycle); /** * Performs a buffer-to-buffer copy. @@ -2176,21 +3508,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the buffer and offset to copy from. * \param destination the buffer and offset to copy to. * \param size the length of the buffer to copy. - * \param cycle if SDL_TRUE, cycles the destination buffer if it is bound, + * \param cycle if true, cycles the destination buffer if it is already bound, * otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferLocation *source, - SDL_GPUBufferLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, Uint32 size, - SDL_bool cycle); + bool cycle); /** * Copies data from a texture to a transfer buffer on the GPU timeline. @@ -2198,17 +3530,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source texture region. * \param destination the destination transfer buffer with image layout * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureRegion *source, - SDL_GPUTextureTransferInfo *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); /** * Copies data from a buffer to a transfer buffer on the GPU timeline. @@ -2216,39 +3548,39 @@ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source buffer with offset and size. * \param destination the destination transfer buffer with offset. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferRegion *source, - SDL_GPUTransferBufferLocation *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); /** * Ends the current copy pass. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( - SDL_GPUCopyPass *copyPass); + SDL_GPUCopyPass *copy_pass); /** * Generates mipmaps for the given texture. * * This function must not be called inside of any pass. * - * \param commandBuffer a commandBuffer. + * \param command_buffer a command_buffer. * \param texture a texture with more than 1 mip level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, SDL_GPUTexture *texture); /** @@ -2256,23 +3588,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( * * This function must not be called inside of any pass. * - * \param commandBuffer a command buffer. - * \param source the texture region to copy from. - * \param destination the texture region to copy to. - * \param flipMode the flip mode for the source texture region. - * \param filterMode the filter mode that will be used when blitting. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination - * texture is bound, otherwise overwrites the data. + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUBlitRegion *source, - SDL_GPUBlitRegion *destination, - SDL_FlipMode flipMode, - SDL_GPUFilter filterMode, - SDL_bool cycle); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); /* Submission/Presentation */ @@ -2283,17 +3606,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( * * \param device a GPU context. * \param window an SDL_Window. - * \param swapchainComposition the swapchain composition to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition); + SDL_GPUSwapchainComposition swapchain_composition); /** * Determines whether a presentation mode is supported by the window. @@ -2302,40 +3625,46 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( * * \param device a GPU context. * \param window an SDL_Window. - * \param presentMode the presentation mode to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUPresentMode presentMode); + SDL_GPUPresentMode present_mode); /** * Claims a window, creating a swapchain structure for it. * * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created * the window. * * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain - * parameters, you must call SetSwapchainParameters after claiming the window. + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. * * \param device a GPU context. * \param window an SDL_Window. - * \returns SDL_TRUE on success, otherwise SDL_FALSE. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. * - * \sa SDL_AcquireGPUSwapchainTexture + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_ReleaseWindowFromGPUDevice * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( SDL_GPUDevice *device, SDL_Window *window); @@ -2345,7 +3674,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( * \param device a GPU context. * \param window an SDL_Window that has been claimed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ @@ -2366,29 +3695,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( * * \param device a GPU context. * \param window an SDL_Window that has been claimed. - * \param swapchainComposition the desired composition of the swapchain. - * \param presentMode the desired present mode for the swapchain. - * \returns SDL_TRUE if successful, SDL_FALSE on error. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGPUSwapchainParameters( +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition, - SDL_GPUPresentMode presentMode); + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture pointer with NULL, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight( + SDL_GPUDevice *device, + Uint32 allowed_frames_in_flight); /** * Obtains the texture format of the swapchain for the given window. * + * Note that this format can change if the swapchain parameters change. + * * \param device a GPU context. * \param window an SDL_Window that has been claimed. * \returns the texture format of the swapchain. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( SDL_GPUDevice *device, @@ -2400,28 +3761,118 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma * When a swapchain texture is acquired on a command buffer, it will * automatically be submitted for presentation when the command buffer is * submitted. The swapchain texture should only be referenced by the command - * buffer used to acquire it. May return NULL under certain conditions. This - * is not necessarily an error. This texture is managed by the implementation - * and must not be freed by the user. You MUST NOT call this function from any - * thread other than the one that created the window. + * buffer used to acquire it. * - * \param commandBuffer a command buffer. + * This function will fill the swapchain texture handle with NULL if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. * \param window a window that has been claimed. - * \param pWidth a pointer filled in with the swapchain width. - * \param pHeight a pointer filled in with the swapchain height. - * \returns a swapchain texture. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight */ -extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( - SDL_GPUCommandBuffer *commandBuffer, +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, SDL_Window *window, - Uint32 *pWidth, - Uint32 *pHeight); + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with NULL in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the pointer is NULL before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); /** * Submits a command buffer so its commands can be processed on the GPU. @@ -2433,16 +3884,19 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( - SDL_GPUCommandBuffer *commandBuffer); +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Submits a command buffer so its commands can be processed on the GPU, and @@ -2456,63 +3910,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. - * \returns a fence associated with the command buffer. + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_ReleaseGPUFence */ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); + +/** + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Blocks the thread until the GPU is completely idle. * * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitForGPUFences */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUIdle( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( SDL_GPUDevice *device); /** * Blocks the thread until the given fences are signaled. * * \param device a GPU context. - * \param waitAll if 0, wait for any fence to be signaled, if 1, wait for all - * fences to be signaled. - * \param pFences an array of fences to wait on. - * \param fenceCount the number of fences in the pFences array. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence * \sa SDL_WaitForGPUIdle */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUFences( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( SDL_GPUDevice *device, - SDL_bool waitAll, - SDL_GPUFence **pFences, - Uint32 fenceCount); + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); /** * Checks the status of a fence. * * \param device a GPU context. * \param fence a fence. - * \returns SDL_TRUE if the fence is signaled, SDL_FALSE if it is not. + * \returns true if the fence is signaled, false if it is not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( SDL_GPUDevice *device, SDL_GPUFence *fence); @@ -2522,7 +4007,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( * \param device a GPU context. * \param fence a fence. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ @@ -2535,15 +4020,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( /** * Obtains the texel block size for a texture format. * - * \param textureFormat the texture format you want to know the texel size of. + * \param format the texture format you want to know the texel size of. * \returns the texel block size of the texture format. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( - SDL_GPUTextureFormat textureFormat); + SDL_GPUTextureFormat format); /** * Determines whether a texture format is supported for a given type and @@ -2555,9 +4040,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( * \param usage a bitmask of all usage scenarios to check. * \returns whether the texture format is supported for this type and usage. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( SDL_GPUDevice *device, SDL_GPUTextureFormat format, SDL_GPUTextureType type, @@ -2568,15 +4053,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( * * \param device a GPU context. * \param format the texture format to check. - * \param sampleCount the sample count to check. + * \param sample_count the sample count to check. * \returns a hardware-specific version of min(preferred, possible). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( SDL_GPUDevice *device, SDL_GPUTextureFormat format, - SDL_GPUSampleCount sampleCount); + SDL_GPUSampleCount sample_count); + +/** + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize( + SDL_GPUTextureFormat format, + Uint32 width, + Uint32 height, + Uint32 depth_or_layer_count); #ifdef SDL_PLATFORM_GDK @@ -2589,7 +4091,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -2604,7 +4106,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h index 285b237..e2f32ff 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,13 +26,14 @@ * * A GUID is a 128-bit value that represents something that is uniquely * identifiable by this value: "globally unique." + * + * SDL provides functions to convert a GUID to/from a string. */ #ifndef SDL_guid_h_ #define SDL_guid_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -55,7 +56,7 @@ extern "C" { * GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs on different operating systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GUID { Uint8 data[16]; @@ -70,7 +71,7 @@ typedef struct SDL_GUID { * \param pszGUID buffer in which to write the ASCII string. * \param cbGUID the size of pszGUID, should be at least 33 bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StringToGUID */ @@ -86,7 +87,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_GUID structure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h index 95446fe..a45335b 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -66,7 +66,7 @@ * Complete example: * * ```c - * SDL_bool test_haptic(SDL_Joystick *joystick) + * bool test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -74,12 +74,12 @@ * * // Open the device * haptic = SDL_OpenHapticFromJoystick(joystick); - * if (haptic == NULL) return SDL_FALSE; // Most likely joystick isn't haptic + * if (haptic == NULL) return false; // Most likely joystick isn't haptic * * // See if it can do sine waves * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) { * SDL_CloseHaptic(haptic); // No sine effect - * return SDL_FALSE; + * return false; * } * * // Create the effect @@ -106,7 +106,7 @@ * // Close the device * SDL_CloseHaptic(haptic); * - * return SDL_TRUE; // Success + * return true; // Success * } * ``` * @@ -139,15 +139,14 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_OpenHaptic - * \sa SDL_OpenHapticFromJoystick - * \sa SDL_CloseHaptic + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct SDL_Haptic; typedef struct SDL_Haptic SDL_Haptic; @@ -168,7 +167,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Constant haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -179,7 +178,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates sine waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -190,7 +189,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates square waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -201,7 +200,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates triangular waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -212,7 +211,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth up waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -223,7 +222,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth down waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -234,7 +233,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Ramp haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticRamp */ @@ -246,7 +245,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates a spring. Effect is based on the * axes position. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -258,7 +257,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -270,7 +269,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -282,7 +281,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates friction. Effect is based on the * axes movement. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -293,19 +292,31 @@ typedef struct SDL_Haptic SDL_Haptic; * * Haptic effect for direct control over high/low frequency motors. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** @@ -313,7 +324,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * User defined custom haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_CUSTOM (1u<<15) @@ -326,7 +337,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting the global gain. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticGain */ @@ -337,7 +348,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting autocenter. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticAutocenter */ @@ -348,7 +359,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports querying effect status. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus */ @@ -359,7 +370,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Devices supports being paused. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_PauseHaptic * \sa SDL_ResumeHaptic @@ -375,7 +386,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses polar coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -384,7 +395,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses cartesian coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -393,7 +404,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses spherical coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -405,7 +416,7 @@ typedef struct SDL_Haptic SDL_Haptic; * This provides better compatibility across platforms and devices as SDL will * guess the correct axis. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -422,7 +433,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Used to play a device an infinite number of times. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect */ @@ -523,7 +534,7 @@ typedef struct SDL_Haptic SDL_Haptic; * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN @@ -547,7 +558,7 @@ typedef struct SDL_HapticDirection * A constant effect applies a constant force in the specified direction to * the joystick. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect @@ -629,7 +640,7 @@ typedef struct SDL_HapticConstant * \| \| \| \| \| \| \| * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE @@ -685,7 +696,7 @@ typedef struct SDL_HapticPeriodic * SDL_HapticDirection diagram for which side is positive and which is * negative. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticDirection * \sa SDL_HAPTIC_SPRING @@ -699,7 +710,7 @@ typedef struct SDL_HapticCondition /* Header */ Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -728,7 +739,7 @@ typedef struct SDL_HapticCondition * effects get added to the ramp effect making the effect become quadratic * instead of linear. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect @@ -767,7 +778,7 @@ typedef struct SDL_HapticRamp * motors, commonly found in modern game controllers. The small (right) motor * is high frequency, and the large (left) motor is low frequency. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HapticEffect @@ -797,7 +808,7 @@ typedef struct SDL_HapticLeftRight * If channels is one, the effect is rotated using the defined direction. * Otherwise it uses the samples in data for the different axes. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CUSTOM * \sa SDL_HapticEffect @@ -892,7 +903,7 @@ typedef struct SDL_HapticCustom * Note either the attack_level or the fade_level may be above the actual * effect level. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic @@ -921,7 +932,7 @@ typedef union SDL_HapticEffect * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_HapticID; @@ -937,7 +948,7 @@ typedef Uint32 SDL_HapticID; * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -953,7 +964,7 @@ extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticName * \sa SDL_OpenHaptic @@ -974,7 +985,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID ins * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_GetHaptics @@ -993,7 +1004,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id); @@ -1004,7 +1015,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instan * \returns the instance ID of the specified haptic device on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); @@ -1016,7 +1027,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticNameForID */ @@ -1025,13 +1036,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromMouse */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -1039,7 +1050,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); * \returns the haptic device identifier or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsMouseHaptic @@ -1050,13 +1061,13 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. + * \returns true if the joystick is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -1073,7 +1084,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick * \returns a valid haptic device identifier on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsJoystickHaptic @@ -1085,7 +1096,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick * * \param haptic the SDL_Haptic device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -1102,7 +1113,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic); * \returns the number of effects the haptic device can store or a negative * error code on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffectsPlaying * \sa SDL_GetHapticFeatures @@ -1118,7 +1129,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); * \returns the number of effects the haptic device can play at the same time * or -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffects * \sa SDL_GetHapticFeatures @@ -1132,7 +1143,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HapticEffectSupported * \sa SDL_GetMaxHapticEffects @@ -1149,7 +1160,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); * \returns the number of axes on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); @@ -1158,14 +1169,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1176,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti * \returns the ID of the effect on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyHapticEffect * \sa SDL_RunHapticEffect @@ -1196,15 +1207,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_RunHapticEffect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1219,31 +1230,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus * \sa SDL_StopHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1254,7 +1265,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, in * \param haptic the SDL_Haptic device to destroy the effect on. * \param effect the ID of the haptic effect to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect */ @@ -1267,14 +1278,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns SDL_TRUE if it is playing, SDL_FALSE if it isn't playing or haptic - * status isn't supported. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1289,14 +1300,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *hapti * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1308,14 +1319,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int g * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. @@ -1327,14 +1338,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** * Resume a haptic device. @@ -1342,55 +1353,55 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1398,28 +1409,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble * \sa SDL_StopHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h index 66bea9d..131b037 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -65,14 +65,14 @@ extern "C" { /** * An opaque handle representing an open HID device. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device SDL_hid_device; /** * HID underlying bus types. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_hid_bus_type { /** Unknown bus type */ @@ -107,7 +107,7 @@ typedef enum SDL_hid_bus_type { /** * Information about a connected HID device * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device_info { @@ -169,7 +169,7 @@ typedef struct SDL_hid_device_info * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_exit */ @@ -184,7 +184,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_init */ @@ -205,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void); * \returns a change counter that is incremented with each potential device * change, or 0 if device change detection isn't available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_enumerate */ @@ -233,7 +233,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); * in the case of failure. Free this linked list by calling * SDL_hid_free_enumeration(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_device_change_count */ @@ -247,7 +247,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho * \param devs pointer to a list of struct_device returned from * SDL_hid_enumerate(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); @@ -265,7 +265,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); @@ -279,7 +279,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_ * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); @@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path) * \returns the actual number of bytes written and -1 on on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne * SDL_GetError() for more information. If no packet was available to * be read within the timeout period, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); @@ -348,7 +348,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign * be read and the handle is in non-blocking mode, this function * returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -367,7 +367,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); @@ -392,7 +392,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int * \returns the actual number of bytes written and -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -415,7 +415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -438,7 +438,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -449,7 +449,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); @@ -462,7 +462,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device * * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -488,7 +488,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -502,7 +502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); @@ -514,7 +514,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, * on failure; call SDL_GetError() for more information. This struct * is valid until the device is closed with SDL_hid_close(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); @@ -530,18 +530,18 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi * \returns the number of bytes actually copied or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. + * \param active true to start the scan, false to stop the scan. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h index 8433240..8f2d074 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,8 +22,6 @@ /** * # CategoryHints * - * Official documentation for SDL configuration variables - * * This file contains functions to set and get configuration hints, as well as * listing each of them alphabetically. * @@ -63,7 +61,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" @@ -83,7 +81,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" @@ -98,10 +96,27 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" +/** + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" + /** * A variable to control whether we trap the Android back button to handle it * manually. @@ -121,7 +136,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" @@ -137,7 +152,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_ID "SDL_APP_ID" @@ -155,7 +170,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_NAME "SDL_APP_NAME" @@ -178,7 +193,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" @@ -193,7 +208,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" @@ -201,16 +216,58 @@ extern "C" { * Specify the default ALSA audio device name. * * This variable is a specific audio device to open when the "default" audio - * device is used. By default if 4 channel audio is requested, the - * "plug:surround40" device will be opened and if 6 channel audio is requested - * the "plug:surround51" device will be opened. + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE */ #define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" +/** + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" + +/** + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" + /** * A variable controlling the audio category on iOS and macOS. * @@ -225,7 +282,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" @@ -238,7 +295,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" @@ -261,7 +318,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" @@ -283,7 +340,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" @@ -310,7 +367,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" @@ -336,7 +393,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" @@ -347,7 +404,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" @@ -358,7 +415,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" @@ -371,7 +428,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" @@ -385,7 +442,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" @@ -398,7 +455,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" @@ -409,18 +466,23 @@ extern "C" { * device, this hint can be used to specify a default format that will be * used. * - * The variable can be set to the following values: - "U8": Unsigned 8-bit - * audio - "S8": Signed 8-bit audio - "S16LE": Signed 16-bit little-endian - * audio - "S16BE": Signed 16-bit big-endian audio - "S16": Signed 16-bit - * native-endian audio (default) - "S32LE": Signed 32-bit little-endian audio - * - "S32BE": Signed 32-bit big-endian audio - "S32": Signed 32-bit - * native-endian audio - "F32LE": Floating point little-endian audio - - * "F32BE": Floating point big-endian audio - "F32": Floating point - * native-endian audio + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" @@ -433,7 +495,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" @@ -456,7 +518,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" @@ -471,7 +533,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" @@ -486,7 +548,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" @@ -509,7 +571,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" @@ -525,7 +587,7 @@ extern "C" { * best camera backend on your behalf. This hint needs to be set before * SDL_Init() is called to be useful. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" @@ -558,7 +620,7 @@ extern "C" { * * The items can be prefixed by '+'/'-' to add/remove features. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" @@ -572,7 +634,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" @@ -601,7 +663,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" @@ -619,7 +681,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" @@ -640,7 +702,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" @@ -653,7 +715,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" @@ -668,12 +730,13 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all * - any other string without a leading # sign applies to the element on the * page with that ID. * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" @@ -690,7 +753,7 @@ extern "C" { * * This hint must be set before SDL_StartTextInput() is called * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" @@ -707,7 +770,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" @@ -731,7 +794,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" @@ -751,7 +814,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" @@ -772,7 +835,7 @@ extern "C" { * * This hint should be set before calling SDL_GetWindowSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" @@ -787,7 +850,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" @@ -803,7 +866,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" @@ -827,7 +890,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" @@ -845,7 +908,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" @@ -863,7 +926,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" @@ -886,7 +949,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" @@ -898,7 +961,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" @@ -910,7 +973,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" @@ -925,7 +988,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" @@ -941,7 +1004,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" @@ -952,7 +1015,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" @@ -970,7 +1033,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" @@ -988,7 +1051,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" @@ -1002,7 +1065,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" @@ -1011,12 +1074,12 @@ extern "C" { * * By default, SDL will try all available GPU backends in a reasonable order * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "d3d11" if, say, your hardware supports - * D3D12 but want to try using D3D11 instead. + * force a specific target, such as "direct3d11" if, say, your hardware + * supports D3D12 but want to try using D3D11 instead. * - * This hint should be set before SDL_GPUSelectBackend() is called. + * This hint should be set before any GPU functions are called. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" @@ -1035,7 +1098,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" @@ -1052,7 +1115,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" @@ -1075,7 +1138,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" @@ -1094,7 +1157,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" @@ -1111,7 +1174,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" @@ -1128,7 +1191,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" @@ -1149,7 +1212,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" @@ -1167,7 +1230,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" @@ -1188,7 +1251,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" @@ -1198,10 +1261,35 @@ extern "C" { * * This variable is currently only used by the Linux joystick driver. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" +/** + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" + /** * A variable containing a list of flightstick style controllers. * @@ -1215,7 +1303,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" @@ -1236,7 +1324,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" @@ -1246,12 +1334,14 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": GameInput is not used. (default) + * - "0": GameInput is not used. * - "1": GameInput is used. * + * The default is "1" on GDK platforms, and "0" otherwise. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" @@ -1269,7 +1359,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" @@ -1290,7 +1380,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" @@ -1305,9 +1395,9 @@ extern "C" { * This variable is the default for all drivers, but can be overridden by the * hints for specific drivers below. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" @@ -1322,9 +1412,9 @@ extern "C" { * - "1": Left and right Joy-Con controllers will be combined into a single * controller. (default) * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" @@ -1339,9 +1429,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" @@ -1362,7 +1452,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" @@ -1377,9 +1467,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" @@ -1398,7 +1488,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" @@ -1413,9 +1503,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" @@ -1430,9 +1520,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" @@ -1452,9 +1542,9 @@ extern "C" { * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" @@ -1469,9 +1559,9 @@ extern "C" { * * The default value is 0. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" @@ -1486,9 +1576,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" @@ -1503,36 +1593,10 @@ extern "C" { * This hint can be set anytime, but only takes effect when extended input * reports are enabled. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" -/** - * A variable controlling whether extended input reports should be used for - * PS4 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports are enabled. - * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value will also control - * the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for PS5 controllers should * be used. @@ -1544,9 +1608,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" @@ -1559,35 +1623,10 @@ extern "C" { * - "0": player LEDs are not enabled. * - "1": player LEDs are enabled. (default) * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" -/** - * A variable controlling whether extended input reports should be used for - * PS5 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports. - * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value defaults to the - * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD * controllers should be used. @@ -1599,9 +1638,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" @@ -1616,7 +1655,7 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" @@ -1631,12 +1670,31 @@ extern "C" { * Bluetooth access and may prompt the user for permission on iOS and * Android. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" +/** + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" + /** * A variable controlling whether the HIDAPI driver for the Steam Deck builtin * controller should be used. @@ -1648,12 +1706,23 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + /** * A variable controlling whether the HIDAPI driver for Nintendo Switch * controllers should be used. @@ -1665,9 +1734,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" @@ -1686,7 +1755,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" @@ -1701,7 +1770,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" @@ -1717,7 +1786,7 @@ extern "C" { * * This hint should be set before opening a Joy-Con controller. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" @@ -1730,12 +1799,12 @@ extern "C" { * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. + * This driver doesn't work with the dolphinbar, so the default is false for + * now. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" @@ -1750,7 +1819,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" @@ -1766,9 +1835,9 @@ extern "C" { * The default is "0" on Windows, otherwise the value of * SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" @@ -1783,9 +1852,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" @@ -1800,7 +1869,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" @@ -1815,9 +1884,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" @@ -1832,9 +1901,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" @@ -1853,7 +1922,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" @@ -1868,7 +1937,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" @@ -1883,7 +1952,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" @@ -1898,7 +1967,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" @@ -1916,7 +1985,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" @@ -1932,7 +2001,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" @@ -1947,7 +2016,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" @@ -1962,7 +2031,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" @@ -1979,7 +2048,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" @@ -1994,7 +2063,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" @@ -2004,12 +2073,12 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": A separate thread is not used. (default) - * - "1": A separate thread is used for handling raw input messages. + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" @@ -2026,7 +2095,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" @@ -2047,7 +2116,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" @@ -2062,7 +2131,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" @@ -2079,7 +2148,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" @@ -2100,7 +2169,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" @@ -2118,7 +2187,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" @@ -2139,7 +2208,7 @@ extern "C" { * - "latin_letters": For keyboards using non-Latin letters, such as Russian * or Thai, the letter keys generate keycodes as though it had an en_US * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian - * keyboard would yield 'a' instead of 'ф'. + * keyboard would yield 'a' instead of a Cyrillic letter. * * The default value for this hint is "french_numbers,latin_letters" * @@ -2152,7 +2221,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" @@ -2166,7 +2235,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" @@ -2194,7 +2263,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" @@ -2220,7 +2289,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_LOGGING "SDL_LOGGING" @@ -2234,9 +2303,9 @@ extern "C" { * (default) * - "1": The application may remain in the background when launched. * - * This hint should be set before applicationDidFinishLaunching() is called. + * This hint needs to be set before SDL_Init(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" @@ -2252,7 +2321,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" @@ -2275,25 +2344,73 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" +/** + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + +/** + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" + /** * Request SDL_AppIterate() be called at a specific rate. * - * This number is in Hz, so "60" means try to iterate 60 times per second. + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. * * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, * this hint is ignored. When the hint can be used, it is allowed to be * changed at any time. * - * This defaults to 60, and specifying NULL for the hint's value will restore + * This defaults to 0, and specifying NULL for the hint's value will restore * the default. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" @@ -2312,7 +2429,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" @@ -2321,7 +2438,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" @@ -2330,10 +2447,22 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" +/** + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" + /** * A variable controlling whether warping a hidden mouse cursor will activate * relative mouse mode. @@ -2362,7 +2491,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" @@ -2376,7 +2505,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" @@ -2386,7 +2515,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" @@ -2407,32 +2536,17 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" -/** - * A variable controlling whether relative mouse mode is implemented using - * mouse warping. - * - * The variable can be set to the following values: - * - * - "0": Relative mouse mode uses raw input. (default) - * - "1": Relative mouse mode uses mouse warping. - * - * This hint can be set anytime relative mode is not currently enabled. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" - /** * A variable setting the scale for mouse motion, in floating point, when the * mouse is in relative mode. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" @@ -2446,12 +2560,12 @@ extern "C" { * - "1": Relative mouse motion will be scaled using the system mouse * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after * system speed scale. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" @@ -2470,7 +2584,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" @@ -2478,9 +2592,10 @@ extern "C" { * A variable controlling whether the hardware cursor stays visible when * relative mode is active. * - * This variable can be set to the following values: "0" - The cursor will be - * hidden while relative mode is active (default) "1" - The cursor will remain - * visible while relative mode is active + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active * * Note that for systems without raw hardware inputs, relative mode is * implemented using warping, so the hardware cursor will visibly warp between @@ -2488,27 +2603,10 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" -/** - * Controls how often SDL issues cursor confinement commands to the operating - * system while relative mode is active, in case the desired confinement state - * became out-of-sync due to interference from other running programs. - * - * The variable can be integers representing miliseconds between each refresh. - * A value of zero means SDL will not automatically refresh the confinement. - * The default value varies depending on the operating system, this variable - * might not have any effects on inapplicable platforms such as those without - * a cursor. - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" - /** * A variable controlling whether mouse events should generate synthetic touch * events. @@ -2522,7 +2620,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" @@ -2540,7 +2638,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" @@ -2555,7 +2653,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" @@ -2563,12 +2661,25 @@ extern "C" { * Specify the OpenGL library to load. * * This hint should be set before creating an OpenGL window or creating an - * OpenGL context. + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" +/** + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" + /** * A variable controlling what driver to use for OpenGL ES contexts. * @@ -2599,10 +2710,22 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" + /** * A variable controlling which orientations are allowed on iOS/Android. * @@ -2618,7 +2741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" @@ -2638,7 +2761,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" @@ -2656,7 +2779,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" @@ -2673,9 +2796,13 @@ extern "C" { * - "1": SDL will send a quit event when the last window is requesting to * close. (default) * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" @@ -2690,7 +2817,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" @@ -2706,7 +2833,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" @@ -2720,7 +2847,7 @@ extern "C" { * * By default, SDL does not use Vulkan Validation Layers. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" @@ -2734,7 +2861,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" @@ -2749,7 +2876,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" @@ -2758,7 +2885,7 @@ extern "C" { * * If the application doesn't pick a specific renderer to use, this variable * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * can't be initialized, creating a renderer will fail. * * This variable is case insensitive and can be set to the following values: * @@ -2770,14 +2897,19 @@ extern "C" { * - "opengles" * - "metal" * - "vulkan" + * - "gpu" * - "software" * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * * The default varies by platform, but it's the first one in the list that is * available on the current platform. * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" @@ -2795,7 +2927,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" @@ -2810,7 +2942,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" @@ -2827,7 +2959,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" @@ -2844,7 +2976,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" @@ -2861,7 +2993,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. * * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED */ @@ -2883,7 +3015,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" @@ -2895,7 +3027,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" @@ -2917,7 +3049,7 @@ extern "C" { * * This hint should be set before calling SDL_DisableScreenSaver() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" @@ -2936,7 +3068,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" @@ -2950,7 +3082,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" @@ -2964,7 +3096,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" @@ -2991,32 +3123,32 @@ extern "C" { * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling * policy * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** * A string specifying additional information to use with - * SDL_SetThreadPriority. + * SDL_SetCurrentThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. * * pthread hint values are "current", "other", "fifo" and "rr". Currently no * other platform hint values are defined but may be in the future. * * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the * distro configured execution budget for rtkit. This budget can be queried - * through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" @@ -3036,7 +3168,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" @@ -3051,7 +3183,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" @@ -3072,7 +3204,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -3087,7 +3219,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" @@ -3101,10 +3233,35 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" +/** + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" + /** * Tell the video driver that we only want a double buffer. * @@ -3124,7 +3281,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" @@ -3136,9 +3293,13 @@ extern "C" { * force a specific target, such as "x11" if, say, you are on Wayland but want * to try talking to the X server instead. * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" @@ -3151,7 +3312,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" @@ -3165,7 +3326,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" @@ -3181,7 +3342,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" @@ -3199,10 +3360,31 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + /** * A variable controlling whether fullscreen windows are minimized when they * lose focus. @@ -3215,7 +3397,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" @@ -3232,7 +3414,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" @@ -3258,7 +3440,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" @@ -3276,7 +3458,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" @@ -3296,7 +3478,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" @@ -3318,7 +3500,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" @@ -3338,7 +3520,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" @@ -3357,6 +3539,8 @@ extern "C" { * * - Rounding errors can result with odd window sizes and/or desktop scales, * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. * - The window may be unusably small on scaled desktops. * - The window may jump in size when moving between displays of different * scale factors. @@ -3375,7 +3559,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" @@ -3397,7 +3581,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" @@ -3412,7 +3596,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" @@ -3431,7 +3615,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" @@ -3445,7 +3629,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" @@ -3456,7 +3640,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" @@ -3465,7 +3649,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" @@ -3474,7 +3658,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" @@ -3488,7 +3672,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" @@ -3503,7 +3687,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" @@ -3518,7 +3702,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" @@ -3529,7 +3713,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" @@ -3542,7 +3726,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" @@ -3557,7 +3741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" @@ -3572,7 +3756,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" @@ -3588,7 +3772,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" @@ -3599,7 +3783,7 @@ extern "C" { * * This hint should be set before calling SDL_Vulkan_CreateSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" @@ -3609,7 +3793,7 @@ extern "C" { * This hint should be set before creating a Vulkan window or calling * SDL_Vulkan_LoadLibrary(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" @@ -3641,7 +3825,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" @@ -3653,7 +3837,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" @@ -3681,7 +3865,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" @@ -3701,7 +3885,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" @@ -3718,7 +3902,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" @@ -3735,7 +3919,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" @@ -3753,7 +3937,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" @@ -3769,7 +3953,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" @@ -3785,7 +3969,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" @@ -3814,7 +3998,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" @@ -3829,7 +4013,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" @@ -3845,7 +4029,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" @@ -3859,7 +4043,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" @@ -3880,7 +4064,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" @@ -3890,9 +4074,18 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** @@ -3917,7 +4110,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" @@ -3934,123 +4127,10 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" -/** - * A variable controlling whether back-button-press events on Windows Phone to - * be marked as handled. - * - * Windows Phone devices typically feature a Back button. When pressed, the OS - * will emit back-button-press events, which apps are expected to handle in an - * appropriate manner. If apps do not explicitly mark these events as - * 'Handled', then the OS will invoke its default behavior for unhandled - * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate - * the app (and attempt to switch to the previous app, or to the device's home - * screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to - * mark back-button-press events as Handled, if and when one is sent to the - * app. - * - * Internally, Windows Phone sends back button events as parameters to special - * back-button-press callback functions. Apps that need to respond to - * back-button-press events are expected to register one or more callback - * functions for such, shortly after being launched (during the app's - * initialization phase). After the back button is pressed, the OS will invoke - * these callbacks. If the app's callback(s) do not explicitly mark the event - * as handled by the time they return, or if the app never registers one of - * these callback, the OS will consider the event un-handled, and it will - * apply its default back button behavior (terminate the app). - * - * SDL registers its own back-button-press callback with the Windows Phone OS. - * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN - * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after - * which it will check the contents of the hint, - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the - * back button event's Handled property will get set to 'true'. If the hint's - * value is set to something else, or if it is unset, SDL will leave the - * event's Handled property alone. (By default, the OS sets this property to - * 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for - * either event type is suitable.) Any value of - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied - * to the OS' current back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found at - * the following page, on Microsoft's developer site: - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** - * A variable specifying the label text for a WinRT app's privacy policy link. - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, - * 8.1, and RT, Microsoft mandates that this policy be available via the - * Windows Settings charm. SDL provides code to add a link there, with its - * label text being set via the optional hint, - * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A - * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the - * actual text of the policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". - * - * For additional information on linking to a privacy policy, see the - * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. - * - * This hint should be set before SDL is initialized. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A variable specifying the URL to a WinRT app's privacy policy. - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - /** * A variable controlling whether X11 windows are marked as override-redirect. * @@ -4068,7 +4148,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" @@ -4085,18 +4165,18 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** * Specify the XCB library to load for the X11 driver. * - * This defaults to "libX11-xcb.so" + * The default is platform-specific, often "libX11-xcb.so.1". * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" @@ -4111,7 +4191,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" @@ -4135,15 +4215,45 @@ extern "C" { * This hint should be set before an assertion failure is triggered and can be * changed at any time. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ASSERT "SDL_ASSERT" +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + /** * An enumeration of hint priorities. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_HintPriority { @@ -4162,18 +4272,18 @@ typedef enum SDL_HintPriority * \param name the hint to set. * \param value the value of the hint variable. * \param priority the SDL_HintPriority level for the hint. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); /** * Set a hint with normal priority. @@ -4184,18 +4294,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, c * * \param name the hint to set. * \param value the value of the hint variable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); /** * Reset a hint to the default value. @@ -4205,17 +4315,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *v * change. * * \param name the hint to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_ResetHints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); /** * Reset all hints to the default values. @@ -4226,7 +4336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetHint */ @@ -4245,7 +4355,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); * callback instead is always thread-safe, as SDL holds a lock * on the thread subsystem during the callback. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_SetHintWithPriority @@ -4262,12 +4372,12 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); /** * A callback used to send notifications of hint value changes. @@ -4284,7 +4394,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo * hint value. SDL holds a lock on the hint subsystem when * calling this callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ @@ -4300,16 +4410,16 @@ typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * \param callback An SDL_HintCallback function that will be called when the * hint value changes. * \param userdata a pointer to pass to the callback function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveHintCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); /** * Remove a function watching a particular hint. @@ -4321,7 +4431,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_H * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h index 5a13947..adf0de8 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,10 +22,30 @@ /** * # CategoryInit * - * SDL subsystem init and quit functions. + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). */ - #ifndef SDL_init_h_ #define SDL_init_h_ @@ -47,7 +67,7 @@ extern "C" { * These are the flags which may be passed to SDL_Init(). You should specify * the subsystems which you will be using in your application. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -57,9 +77,8 @@ extern "C" { */ typedef Uint32 SDL_InitFlags; -#define SDL_INIT_TIMER 0x00000001u #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ -#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */ #define SDL_INIT_HAPTIC 0x00001000u #define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ @@ -85,7 +104,7 @@ typedef Uint32 SDL_InitFlags; * [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. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AppResult { @@ -94,10 +113,70 @@ typedef enum SDL_AppResult SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ } SDL_AppResult; +/** + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); + +/** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ 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); + +/** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); + +/** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. @@ -117,11 +196,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * * `flags` may be any of the following OR'd together: * - * - `SDL_INIT_TIMER`: timer subsystem * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem + * subsystem, should be initialized on the main thread. * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem @@ -143,10 +221,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * SDL_SetAppMetadataProperty(). * * \param flags subsystem initialization flags. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty @@ -155,7 +233,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * \sa SDL_SetMainReady * \sa SDL_WasInit */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Init(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); /** * Compatibility function to initialize the SDL library. @@ -163,16 +241,16 @@ extern SDL_DECLSPEC SDL_bool 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit * \sa SDL_QuitSubSystem */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); /** * Shut down specific SDL subsystems. @@ -182,7 +260,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem * \sa SDL_Quit @@ -196,7 +274,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_InitSubSystem @@ -214,13 +292,70 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); * application is shutdown, but it is not wise to do this from a library or * other dynamically loaded code. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_QuitSubSystem */ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); +/** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void); + +/** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata); + +/** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete); + /** * Specify basic metadata about your app. * @@ -248,16 +383,16 @@ 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadataProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); /** * Specify metadata about your app through a set of properties. @@ -274,7 +409,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * Multiple calls to this function are allowed, but various state might not * change once it has been set up with a previous call to this function. * - * Once set, this metadata can be read using SDL_GetMetadataProperty(). + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). * * These are the supported properties: * @@ -310,17 +445,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * * \param name the name of the metadata property to set. * \param value the value of the property, or NULL to remove that property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); +extern SDL_DECLSPEC 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" @@ -346,7 +481,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name * freed if you call SDL_SetAppMetadataProperty() to set that * property from another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h index efba11d..bac6d7a 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -19,8 +19,31 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * Header file for CPU intrinsics for SDL +/* WIKI CATEGORY: Intrinsics */ + +/** + * # CategoryIntrinsics + * + * SDL does some preprocessor gymnastics to determine if any CPU-specific + * compiler intrinsics are available, as this is not necessarily an easy thing + * to calculate, and sometimes depends on quirks of a system, versions of + * build tools, and other external forces. + * + * Apps including SDL's headers will be able to check consistent preprocessor + * definitions to decide if it's safe to use compiler intrinsics for a + * specific CPU architecture. This check only tells you that the compiler is + * capable of using those intrinsics; at runtime, you should still check if + * they are available on the current system with the + * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo) + * , such as SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash + * for using an unsupported CPU instruction. + * + * SDL only sets preprocessor defines for CPU intrinsics if they are + * supported, so apps should check with `#ifdef` and not `#if`. + * + * SDL will also include the appropriate instruction-set-specific support + * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will also + * `#include ` as well. */ #ifndef SDL_intrin_h_ @@ -28,6 +51,169 @@ #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LSX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LASX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports ARM NEON intrinsics. + * + * If this macro is defined, SDL will have already included `` + * ``, ``, and ``, as appropriate. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NEON_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports PowerPC Altivec intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALTIVEC_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel MMX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + */ +#define SDL_MMX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE3 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE3_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE4_1_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + */ +#define SDL_SSE4_2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX2_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics. + * + * AVX-512F is also sometimes referred to as "AVX-512 Foundation." + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX2_INTRINSICS + */ +#define SDL_AVX512F_INTRINSICS 1 +#endif + /* Need to do this here because intrin.h has C++ code in it */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) @@ -81,7 +267,21 @@ _m_prefetch(void *__P) #endif #endif /* compiler version */ -#if defined(__clang__) && defined(__has_attribute) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro to decide if the compiler supports `__attribute__((target))`. + * + * Even though this is defined in SDL's public headers, it is generally not + * used directly by apps. Apps should probably just use SDL_TARGETING + * directly, instead. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) # if __has_attribute(target) # define SDL_HAS_TARGET_ATTRIBS # endif @@ -91,7 +291,55 @@ _m_prefetch(void *__P) # define SDL_HAS_TARGET_ATTRIBS #endif -#ifdef SDL_HAS_TARGET_ATTRIBS + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a function as targeting a specific CPU architecture. + * + * This is a hint to the compiler that a function should be built with support + * for a CPU instruction set that might be different than the rest of the + * program. + * + * The particulars of this are explained in the GCC documentation: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute + * + * An example of using this feature is to turn on SSE2 support for a specific + * function, even if the rest of the source code is not compiled to use SSE2 + * code: + * + * ```c + * #ifdef SDL_SSE2_INTRINSICS + * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) { + * ...use SSE2 intrinsic functions, etc... + * } + * #endif + * + * // later... + * #ifdef SDL_SSE2_INTRINSICS + * if (SDL_HasSSE2()) { + * DoSomethingWithSSE2(str); + * } + * #endif + * ``` + * + * The application is, on a whole, built without SSE2 instructions, so it will + * run on Intel machines that don't support SSE2. But then at runtime, it + * checks if the system supports the instructions, and then calls into a + * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't + * used on platforms that don't have SSE2 at all. + * + * On compilers without target support, this is defined to nothing. + * + * This symbol is used by SDL internally, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TARGETING(x) __attribute__((target(x))) + +#elif defined(SDL_HAS_TARGET_ATTRIBS) # define SDL_TARGETING(x) __attribute__((target(x))) #else # define SDL_TARGETING(x) diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h index a306deb..4ca1609 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,7 @@ * # CategoryIOStream * * SDL provides an abstract interface for reading and writing data streams. It - * offers implementations for files, memory, etc, and the app can provideo + * offers implementations for files, memory, etc, and the app can provide * their own implementations, too. * * SDL_IOStream is not related to the standard C++ iostream class, other than @@ -48,7 +48,7 @@ extern "C" { /** * SDL_IOStream status, set by a read or write operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOStatus { @@ -66,13 +66,13 @@ typedef enum SDL_IOStatus * These map to the same "whence" concept that `fseek` or `lseek` use in the * standard C runtime. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOWhence { SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ - SDL_IO_SEEK_END, /**< Seek relative to the end of data */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ } SDL_IOWhence; /** @@ -83,10 +83,17 @@ typedef enum SDL_IOWhence * already offers several common types of I/O streams, via functions like * SDL_IOFromFile() and SDL_IOFromMem(). * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_IOStreamInterface { + /* The version of this interface */ + Uint32 version; + /** * Return the number of bytes in this SDL_IOStream * @@ -126,18 +133,41 @@ typedef struct SDL_IOStreamInterface */ size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + /** * Close and free any allocated resources. * - * The SDL_IOStream is still destroyed even if this fails, so clean up anything - * even if flushing to disk returns an error. + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. * - * \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data. + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); } SDL_IOStreamInterface; +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); /** * The read/write operation structure. @@ -147,7 +177,7 @@ typedef struct SDL_IOStreamInterface * SDL_OpenIO() to provide their own stream implementation behind this * struct's abstract interface. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_IOStream SDL_IOStream; @@ -217,6 +247,8 @@ typedef struct SDL_IOStream SDL_IOStream; * than your app, trying to use this pointer will almost certainly result in * a crash! This is mostly a problem on Windows; make sure you build SDL and * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access * the filesystem. If SDL used some other method to access the filesystem, @@ -228,9 +260,12 @@ typedef struct SDL_IOStream SDL_IOStream; * \returns a pointer to the SDL_IOStream structure that is created or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -240,6 +275,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" /** @@ -257,15 +293,25 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromConstMem * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -273,6 +319,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons */ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + /** * Use this function to prepare a read-only memory buffer for use with * SDL_IOStream. @@ -290,12 +339,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * If you need to write to a memory buffer, you should use SDL_IOFromMem() * with a writable buffer of memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromMem * \sa SDL_CloseIO @@ -323,7 +381,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO * \sa SDL_ReadIO @@ -347,20 +407,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * read/write a common data source, you should use the built-in * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. * - * You must free the returned pointer with SDL_CloseIO(). - * * This function makes a copy of `iface` and the caller does not need to keep - * this data around after this call. + * it around after this call. * - * \param iface the function pointers that implement this SDL_IOStream. - * \param userdata the app-controlled pointer that is passed to iface's - * functions when called. + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a pointer to the allocated memory on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE * \sa SDL_IOFromConstMem * \sa SDL_IOFromFile * \sa SDL_IOFromMem @@ -372,21 +433,32 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any * resources used by the stream and frees the SDL_IOStream itself. This - * returns SDL_TRUE on success, or SDL_FALSE if the stream failed to flush to - * its output (e.g. to disk). + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). * - * Note that if this fails to flush the stream to disk, this function reports - * an error, but the SDL_IOStream is still invalid once this function returns. + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. * * \param context SDL_IOStream structure to close. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenIO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); /** * Get the properties associated with an SDL_IOStream. @@ -395,7 +467,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); @@ -413,10 +487,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *c * \param context the SDL_IOStream to query. * \returns an SDL_IOStatus enum with the current state. * - * \threadsafety This function should not be called at the same time that - * another thread is operating on the same SDL_IOStream. + * \threadsafety This function is not thread safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); @@ -428,7 +501,9 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); * negative error code on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); @@ -450,10 +525,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * negative. * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, * `SDL_IO_SEEK_END`. - * \returns the final offset in the data stream after the seek or a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TellIO */ @@ -471,7 +548,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs * \returns the current offset in the stream, or -1 if the information can not * be determined. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SeekIO */ @@ -481,10 +560,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * Read from a data source. * * This function reads up `size` bytes from the data source to the area - * pointed at by `ptr`. This function may read less bytes than requested. It - * will return zero when the data stream is completely read, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR. + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. * * \param context a pointer to an SDL_IOStream structure. * \param ptr a pointer to a buffer to read data into. @@ -492,7 +573,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * \returns the number of bytes read, or 0 on end of file or other failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WriteIO * \sa SDL_GetIOStatus @@ -519,11 +602,14 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \returns the number of bytes written, which will be less than `size` on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_ReadIO * \sa SDL_SeekIO + * \sa SDL_FlushIO * \sa SDL_GetIOStatus */ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); @@ -540,7 +626,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOvprintf * \sa SDL_WriteIO @@ -558,13 +646,35 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_WriteIO */ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + /** * Load all the data from an SDL data stream. * @@ -575,17 +685,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * The data should be freed with SDL_free(). * * \param src the SDL_IOStream to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio); +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); /** * Load all the data from a file path. @@ -601,12 +715,55 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile */ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); +/** + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); + +/** + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); + /** * \name Read endian functions * @@ -617,26 +774,63 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi /** * Use this function to read a byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure or EOF; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); /** * Use this function to read a signed byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of little-endian data from an @@ -645,30 +839,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value) * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data. - * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); - -/** - * Use this function to read 16 bits of little-endian data from an - * SDL_IOStream and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -677,14 +862,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -693,14 +885,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -709,14 +908,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -725,14 +931,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -741,14 +954,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -757,14 +977,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -773,14 +1000,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -789,14 +1023,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -805,14 +1046,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -821,14 +1069,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); /* @} *//* Read endian functions */ /** @@ -843,24 +1098,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); /** * Use this function to write a signed byte to an SDL_IOStream. * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -872,12 +1131,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value) * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -889,12 +1150,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -905,12 +1168,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -921,12 +1186,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -938,12 +1205,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -955,12 +1224,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -971,12 +1242,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -987,12 +1260,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1004,12 +1279,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1021,12 +1298,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1037,12 +1316,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1053,12 +1334,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); /* @} *//* Write endian functions */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h index 43bc1e9..d15668b 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,8 +25,8 @@ * SDL joystick support. * * This is the lower-level joystick handling. If you want the simpler option, - * where what buttons does what is well-defined, you should use the gamepad - * API instead. + * where what each button does is well-defined, you should use the gamepad API + * instead. * * The term "instance_id" is the current instantiation of a joystick device in * the system, if the joystick is removed and then re-inserted then it will @@ -81,7 +81,7 @@ extern SDL_Mutex *SDL_joystick_lock; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Joystick SDL_Joystick; @@ -93,7 +93,7 @@ typedef struct SDL_Joystick SDL_Joystick; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_JoystickID; @@ -107,7 +107,7 @@ typedef Uint32 SDL_JoystickID; * This is by no means a complete list of everything that can be plugged into * a computer. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickType { @@ -120,7 +120,8 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_GUITAR, SDL_JOYSTICK_TYPE_DRUM_KIT, SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT } SDL_JoystickType; /** @@ -129,7 +130,7 @@ typedef enum SDL_JoystickType * This is used by SDL_GetJoystickConnectionState to report how a device is * connected to the system. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickConnectionState { @@ -142,7 +143,7 @@ typedef enum SDL_JoystickConnectionState /** * The largest value an SDL_Joystick's axis can report. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MIN */ @@ -153,19 +154,13 @@ typedef enum SDL_JoystickConnectionState * * This is a negative number! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MAX */ #define SDL_JOYSTICK_AXIS_MIN -32768 -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - /* Function prototypes */ /** @@ -175,27 +170,27 @@ typedef enum SDL_JoystickConnectionState * joysticks while processing to guarantee that the joystick list won't change * and joystick and gamepad events will not be delivered. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); /** * Unlocking for atomic access to the joystick API. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); /** * Return whether a joystick is currently connected. * - * \returns SDL_TRUE if a joystick is connected, SDL_FALSE otherwise. + * \returns true if a joystick is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. @@ -206,7 +201,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasJoystick * \sa SDL_OpenJoystick @@ -222,7 +217,7 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickName * \sa SDL_GetJoysticks @@ -238,7 +233,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPath * \sa SDL_GetJoysticks @@ -253,7 +248,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a joystick, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoysticks @@ -269,7 +264,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID i * \returns the GUID of the selected joystick. If called with an invalid * instance_id, this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUID * \sa SDL_GUIDToString @@ -286,7 +281,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID ins * \returns the USB vendor ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendor * \sa SDL_GetJoysticks @@ -303,7 +298,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID ins * \returns the USB product ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProduct * \sa SDL_GetJoysticks @@ -320,7 +315,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID in * \returns the product version of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersion * \sa SDL_GetJoysticks @@ -337,7 +332,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_Joysti * invalid instance_id, this function returns * `SDL_JOYSTICK_TYPE_UNKNOWN`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickType * \sa SDL_GetJoysticks @@ -354,7 +349,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti * \returns a joystick identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseJoystick */ @@ -367,7 +362,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID insta * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); @@ -378,7 +373,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_SetJoystickPlayerIndex @@ -388,7 +383,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int pl /** * The structure that describes a virtual joystick touchpad. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -401,7 +396,7 @@ typedef struct SDL_VirtualJoystickTouchpadDesc /** * The structure that describes a virtual joystick sensor. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -414,16 +409,19 @@ typedef struct SDL_VirtualJoystickSensorDesc /** * The structure that describes a virtual joystick. * - * All elements of this structure are optional and can be left 0. + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE * \sa SDL_VirtualJoystickSensorDesc * \sa SDL_VirtualJoystickTouchpadDesc */ typedef struct SDL_VirtualJoystickDesc { + Uint32 version; /**< the version of this interface */ Uint16 type; /**< `SDL_JoystickType` */ Uint16 padding; /**< unused */ Uint16 vendor_id; /**< the USB vendor ID of this joystick */ @@ -446,22 +444,32 @@ typedef struct SDL_VirtualJoystickDesc void *userdata; /**< User data pointer passed to callbacks */ void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - SDL_bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - SDL_bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - SDL_bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - SDL_bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - SDL_bool (SDLCALL *SetSensorsEnabled)(void *userdata, SDL_bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ } SDL_VirtualJoystickDesc; +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + /** * Attach a new virtual joystick. * - * \param desc joystick description. + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DetachVirtualJoystick */ @@ -472,24 +480,24 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V * * \param instance_id the joystick instance ID, previously returned from * SDL_AttachVirtualJoystick(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); /** * Query whether or not a joystick is virtual. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * \returns true if the joystick is virtual, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); /** * Set the state of an axis on an opened virtual joystick. @@ -507,12 +515,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instan * \param joystick the virtual joystick on which to set state. * \param axis the index of the axis on the virtual joystick to update. * \param value the new value for the specified axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); /** * Generate ball motion on an opened virtual joystick. @@ -527,12 +535,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *jo * \param ball the index of the ball on the virtual joystick to update. * \param xrel the relative motion on the X axis. * \param yrel the relative motion on the Y axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); /** * Set the state of a button on an opened virtual joystick. @@ -545,13 +553,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *jo * * \param joystick the virtual joystick on which to set state. * \param button the index of the button on the virtual joystick to update. - * \param value the new value for the specified button. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); /** * Set the state of a hat on an opened virtual joystick. @@ -565,12 +573,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick * * \param joystick the virtual joystick on which to set state. * \param hat the index of the hat on the virtual joystick to update. * \param value the new value for the specified hat. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); /** * Set touchpad finger state on an opened virtual joystick. @@ -585,19 +593,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joy * \param touchpad the index of the touchpad on the virtual joystick to * update. * \param finger the index of the finger on the touchpad to set. - * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the - * finger is released. + * \param down true if the finger is pressed, false if the finger is released. * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param pressure the pressure of the finger. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); /** * Send a sensor update for an opened virtual joystick. @@ -614,12 +621,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick * the sensor reading. * \param data the data associated with the sensor reading. * \param num_values the number of values pointed to by `data`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); /** * Get the properties associated with a joystick. @@ -641,7 +648,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joyst * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); @@ -658,7 +665,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickNameForID */ @@ -671,7 +678,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPathForID */ @@ -686,7 +693,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joyst * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the player index, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickPlayerIndex */ @@ -698,14 +705,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param player_index player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); /** * Get the implementation-dependent GUID for the joystick. @@ -717,7 +724,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *jo * this function returns a zero GUID; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GUIDToString @@ -732,7 +739,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendorForID */ @@ -746,7 +753,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductForID */ @@ -760,7 +767,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the product version of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersionForID */ @@ -775,7 +782,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j * \returns the firmware version of the selected joystick, or 0 if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); @@ -788,7 +795,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick * * \returns the serial number of the selected joystick, or NULL if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); @@ -798,7 +805,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the SDL_JoystickType of the selected joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickTypeForID */ @@ -817,7 +824,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j * \param crc16 a pointer filled in with a CRC used to distinguish different * products with the same VID/PID, or 0 if not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID */ @@ -827,12 +834,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 * * Get the status of a specified joystick. * * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); /** * Get the instance ID of an opened joystick. @@ -841,7 +848,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic * \returns the instance ID of the specified joystick on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); @@ -856,7 +863,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst * \returns the number of axis controls/number of axes on success or -1 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickAxis * \sa SDL_GetNumJoystickBalls @@ -877,7 +884,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); * \returns the number of trackballs on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickBall * \sa SDL_GetNumJoystickAxes @@ -893,7 +900,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); * \returns the number of POV hats on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickHat * \sa SDL_GetNumJoystickAxes @@ -909,7 +916,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); * \returns the number of buttons on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickButton * \sa SDL_GetNumJoystickAxes @@ -927,12 +934,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick * * \param enabled whether to process joystick events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_JoystickEventsEnabled * \sa SDL_UpdateJoysticks */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); /** * Query the state of joystick event processing. @@ -941,14 +948,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); * yourself and check the state of the joystick when you want joystick * information. * - * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE - * otherwise. + * \returns true if joystick events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); /** * Update the current state of the open joysticks. @@ -956,7 +962,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); * This is called automatically by the event loop if any joystick events are * enabled. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); @@ -978,7 +984,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); * \returns a 16-bit signed integer representing the current position of the * axis or 0 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickAxes */ @@ -994,11 +1000,11 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i * \param joystick an SDL_Joystick structure containing joystick information. * \param axis the axis to query; the axis indices start at index 0. * \param state upon return, the initial value is supplied here. - * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \returns true if this axis has any initial value, or false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); /** * Get the ball axis change since the last poll. @@ -1012,14 +1018,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic * \param ball the ball index to query; ball indices start at index 0. * \param dx stores the difference in the x axis position since the last poll. * \param dy stores the difference in the y axis position since the last poll. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickBalls */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); /** * Get the current state of a POV hat on a joystick. @@ -1030,7 +1036,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickHats */ @@ -1052,13 +1058,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickButtons */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); /** * Start a rumble effect. @@ -1075,11 +1081,11 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE, or SDL_FALSE if rumble isn't supported on this joystick. + * \returns true, or false if rumble isn't supported on this joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the joystick's triggers. @@ -1101,14 +1107,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a joystick's LED color. @@ -1123,12 +1129,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *jo * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** * Send a joystick specific effect packet. @@ -1136,19 +1142,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, * \param joystick the joystick to affect. * \param data the data to send to the joystick. * \param size the size of the data to send to the joystick. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); /** * Close a joystick previously opened with SDL_OpenJoystick(). * * \param joystick the joystick device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenJoystick */ @@ -1162,7 +1168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); @@ -1183,7 +1189,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h index ec6c3f2..afa77b6 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeyboard * * SDL keyboard management. + * + * Please refer to the Best Keyboard Practices document for details on how + * best to accept keyboard input in various types of programs: + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keyboard_h_ @@ -31,6 +36,9 @@ #include #include #include +#include +#include +#include #include #include @@ -47,7 +55,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_KeyboardID; @@ -56,13 +64,15 @@ typedef Uint32 SDL_KeyboardID; /** * Return whether a keyboard is currently connected. * - * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise. + * \returns true if a keyboard is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); /** * Get a list of currently connected keyboards. @@ -78,7 +88,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardNameForID * \sa SDL_HasKeyboard @@ -94,7 +106,9 @@ extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); * \returns the name of the selected keyboard or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ @@ -105,7 +119,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID * * \returns the window with keyboard focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); @@ -116,9 +132,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * valid for the whole lifetime of the application and should not be freed by * the caller. * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. + * A array element with a value of true means that the key is pressed and a + * value of false means that it is not. Indexes into this array are obtained + * by using SDL_Scancode values. * * Use SDL_PumpEvents() to update the state array. * @@ -133,19 +149,23 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PumpEvents * \sa SDL_ResetKeyboard */ -extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys); +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); /** * Clear the state of the keyboard. * * This function will generate key up events for all pressed keys. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState */ @@ -157,7 +177,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); * \returns an OR'd combination of the modifier keys for the keyboard. See * SDL_Keymod for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState * \sa SDL_SetModState @@ -177,7 +199,9 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * * \param modstate the desired SDL_Keymod for the keyboard. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetModState */ @@ -189,21 +213,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * If you want to get the keycode as it would be delivered in key events, * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should - * pass `key_event` as SDL_TRUE. Otherwise this function simply translates the + * pass `key_event` as true. Otherwise this function simply translates the * scancode based on the given modifier state. * * \param scancode the desired SDL_Scancode to query. * \param modstate the modifier state to use when translating the scancode to * a keycode. - * \param key_event SDL_TRUE if the keycode will be used in key events. + * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyName * \sa SDL_GetScancodeFromKey */ -extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, SDL_bool key_event); +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); /** * Get the scancode corresponding to the given key code according to the @@ -217,7 +243,9 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan * scancode generates this key, may be NULL. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetScancodeName @@ -231,14 +259,16 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \param name the name to use for the scancode, encoded as UTF-8. The string * is not copied, so the pointer given to this function must stay * valid while SDL is being used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeName */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); /** * Get a human-readable name for a scancode. @@ -256,7 +286,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, * \returns a pointer to the name for the scancode. If the scancode doesn't * have a name this function returns an empty string (""). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeFromKey * \sa SDL_GetScancodeFromName @@ -271,7 +303,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scanco * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't * recognized; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetScancodeFromKey @@ -284,10 +318,14 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * * If the key doesn't have a name, this function returns an empty string (""). * + * Letters will be presented in their uppercase form, if applicable. + * * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetKeyFromScancode @@ -302,7 +340,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetKeyName @@ -319,20 +359,24 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * \param window the window to enable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInputWithProperties * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); /** * Text input type. @@ -341,7 +385,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); * value is valid on every platform, but where a value isn't supported, a * reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -361,12 +405,11 @@ typedef enum SDL_TextInputType /** * Auto capitalization type. * - * These are the valid values for - * SDL_PROP_TEXTINPUT_AUTOCAPITALIZATION_NUMBER. Not every value is valid on - * every platform, but where a value isn't supported, a reasonable fallback - * will be used. + * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. + * Not every value is valid on every platform, but where a value isn't + * supported, a reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -388,7 +431,9 @@ typedef enum SDL_Capitalization * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * These are the supported properties: * @@ -400,11 +445,11 @@ typedef enum SDL_Capitalization * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail * addresses, usernames, and passwords. * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion - * and auto correction, defaults to SDL_TRUE. + * and auto correction, defaults to true. * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text - * are allowed. This defaults to SDL_TRUE if SDL_HINT_RETURN_KEY_HIDES_IME - * is "0" or is not set, and defaults to SDL_FALSE if - * SDL_HINT_RETURN_KEY_HIDES_IME is "1". + * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is + * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME + * is "1". * * On Android you can directly specify the input type: * @@ -414,17 +459,19 @@ typedef enum SDL_Capitalization * * \param window the window to enable text input. * \param props the properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInput * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" @@ -436,13 +483,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window * Check whether or not Unicode text input events are enabled for a window. * * \param window the window to check. - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * \returns true if text input events are enabled else false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); /** * Stop receiving any text input events in a window. @@ -451,28 +500,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); * it. * * \param window the window to disable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); /** * Dismiss the composition window/IME without disabling the subsystem. * * \param window the window to affect. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); /** * Set the area used to type Unicode text input. @@ -485,15 +538,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); * coordinates, or NULL to clear it. * \param cursor the offset of the current cursor location relative to * `rect->x`, in window coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextInputArea * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); /** * Get the area used to type Unicode text input. @@ -505,39 +560,45 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, co * may be NULL. * \param cursor a pointer to the offset of the current cursor location * relative to `rect->x`, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); /** * Check whether the platform has screen keyboard support. * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. + * \returns true if the platform has some screen keyboard support or false if + * not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_ScreenKeyboardShown */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * Check whether the screen keyboard is shown for given window. * * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * \returns true if screen keyboard is shown or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasScreenKeyboardSupport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h index 2d03a3d..61b68e7 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeycode * * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keycode_h_ @@ -42,272 +47,284 @@ * A special exception is the number keys at the top of the keyboard which map * to SDLK_0...SDLK_9 on AZERTY layouts. * - * \since This datatype is available since SDL 3.0.0. + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_Keycode; -#define SDLK_SCANCODE_MASK (1u<<30) +#define SDLK_EXTENDED_MASK (1u << 29) +#define SDLK_SCANCODE_MASK (1u << 30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -#define SDLK_UNKNOWN 0x00000000u /* 0 */ -#define SDLK_RETURN 0x0000000du /* '\r' */ -#define SDLK_ESCAPE 0x0000001bu /* '\x1B' */ -#define SDLK_BACKSPACE 0x00000008u /* '\b' */ -#define SDLK_TAB 0x00000009u /* '\t' */ -#define SDLK_SPACE 0x00000020u /* ' ' */ -#define SDLK_EXCLAIM 0x00000021u /* '!' */ -#define SDLK_DBLAPOSTROPHE 0x00000022u /* '"' */ -#define SDLK_HASH 0x00000023u /* '#' */ -#define SDLK_DOLLAR 0x00000024u /* '$' */ -#define SDLK_PERCENT 0x00000025u /* '%' */ -#define SDLK_AMPERSAND 0x00000026u /* '&' */ -#define SDLK_APOSTROPHE 0x00000027u /* '\'' */ -#define SDLK_LEFTPAREN 0x00000028u /* '(' */ -#define SDLK_RIGHTPAREN 0x00000029u /* ')' */ -#define SDLK_ASTERISK 0x0000002au /* '*' */ -#define SDLK_PLUS 0x0000002bu /* '+' */ -#define SDLK_COMMA 0x0000002cu /* ',' */ -#define SDLK_MINUS 0x0000002du /* '-' */ -#define SDLK_PERIOD 0x0000002eu /* '.' */ -#define SDLK_SLASH 0x0000002fu /* '/' */ -#define SDLK_0 0x00000030u /* '0' */ -#define SDLK_1 0x00000031u /* '1' */ -#define SDLK_2 0x00000032u /* '2' */ -#define SDLK_3 0x00000033u /* '3' */ -#define SDLK_4 0x00000034u /* '4' */ -#define SDLK_5 0x00000035u /* '5' */ -#define SDLK_6 0x00000036u /* '6' */ -#define SDLK_7 0x00000037u /* '7' */ -#define SDLK_8 0x00000038u /* '8' */ -#define SDLK_9 0x00000039u /* '9' */ -#define SDLK_COLON 0x0000003au /* ':' */ -#define SDLK_SEMICOLON 0x0000003bu /* ';' */ -#define SDLK_LESS 0x0000003cu /* '<' */ -#define SDLK_EQUALS 0x0000003du /* '=' */ -#define SDLK_GREATER 0x0000003eu /* '>' */ -#define SDLK_QUESTION 0x0000003fu /* '?' */ -#define SDLK_AT 0x00000040u /* '@' */ -#define SDLK_LEFTBRACKET 0x0000005bu /* '[' */ -#define SDLK_BACKSLASH 0x0000005cu /* '\\' */ -#define SDLK_RIGHTBRACKET 0x0000005du /* ']' */ -#define SDLK_CARET 0x0000005eu /* '^' */ -#define SDLK_UNDERSCORE 0x0000005fu /* '_' */ -#define SDLK_GRAVE 0x00000060u /* '`' */ -#define SDLK_A 0x00000061u /* 'a' */ -#define SDLK_B 0x00000062u /* 'b' */ -#define SDLK_C 0x00000063u /* 'c' */ -#define SDLK_D 0x00000064u /* 'd' */ -#define SDLK_E 0x00000065u /* 'e' */ -#define SDLK_F 0x00000066u /* 'f' */ -#define SDLK_G 0x00000067u /* 'g' */ -#define SDLK_H 0x00000068u /* 'h' */ -#define SDLK_I 0x00000069u /* 'i' */ -#define SDLK_J 0x0000006au /* 'j' */ -#define SDLK_K 0x0000006bu /* 'k' */ -#define SDLK_L 0x0000006cu /* 'l' */ -#define SDLK_M 0x0000006du /* 'm' */ -#define SDLK_N 0x0000006eu /* 'n' */ -#define SDLK_O 0x0000006fu /* 'o' */ -#define SDLK_P 0x00000070u /* 'p' */ -#define SDLK_Q 0x00000071u /* 'q' */ -#define SDLK_R 0x00000072u /* 'r' */ -#define SDLK_S 0x00000073u /* 's' */ -#define SDLK_T 0x00000074u /* 't' */ -#define SDLK_U 0x00000075u /* 'u' */ -#define SDLK_V 0x00000076u /* 'v' */ -#define SDLK_W 0x00000077u /* 'w' */ -#define SDLK_X 0x00000078u /* 'x' */ -#define SDLK_Y 0x00000079u /* 'y' */ -#define SDLK_Z 0x0000007au /* 'z' */ -#define SDLK_LEFTBRACE 0x0000007bu /* '{' */ -#define SDLK_PIPE 0x0000007cu /* '|' */ -#define SDLK_RIGHTBRACE 0x0000007du /* '}' */ -#define SDLK_TILDE 0x0000007eu /* '~' */ -#define SDLK_DELETE 0x0000007fu /* '\x7F' */ -#define SDLK_PLUSMINUS 0x000000b1u /* '±' */ -#define SDLK_CAPSLOCK 0x40000039u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ -#define SDLK_F1 0x4000003au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ -#define SDLK_F2 0x4000003bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ -#define SDLK_F3 0x4000003cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ -#define SDLK_F4 0x4000003du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ -#define SDLK_F5 0x4000003eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ -#define SDLK_F6 0x4000003fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ -#define SDLK_F7 0x40000040u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ -#define SDLK_F8 0x40000041u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ -#define SDLK_F9 0x40000042u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ -#define SDLK_F10 0x40000043u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ -#define SDLK_F11 0x40000044u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ -#define SDLK_F12 0x40000045u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ -#define SDLK_PRINTSCREEN 0x40000046u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ -#define SDLK_SCROLLLOCK 0x40000047u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ -#define SDLK_PAUSE 0x40000048u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ -#define SDLK_INSERT 0x40000049u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ -#define SDLK_HOME 0x4000004au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ -#define SDLK_PAGEUP 0x4000004bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ -#define SDLK_END 0x4000004du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ -#define SDLK_PAGEDOWN 0x4000004eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ -#define SDLK_RIGHT 0x4000004fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ -#define SDLK_LEFT 0x40000050u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ -#define SDLK_DOWN 0x40000051u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ -#define SDLK_UP 0x40000052u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ -#define SDLK_NUMLOCKCLEAR 0x40000053u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ -#define SDLK_KP_DIVIDE 0x40000054u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ -#define SDLK_KP_MULTIPLY 0x40000055u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ -#define SDLK_KP_MINUS 0x40000056u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ -#define SDLK_KP_PLUS 0x40000057u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ -#define SDLK_KP_ENTER 0x40000058u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ -#define SDLK_KP_1 0x40000059u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ -#define SDLK_KP_2 0x4000005au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ -#define SDLK_KP_3 0x4000005bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ -#define SDLK_KP_4 0x4000005cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ -#define SDLK_KP_5 0x4000005du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ -#define SDLK_KP_6 0x4000005eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ -#define SDLK_KP_7 0x4000005fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ -#define SDLK_KP_8 0x40000060u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ -#define SDLK_KP_9 0x40000061u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ -#define SDLK_KP_0 0x40000062u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ -#define SDLK_KP_PERIOD 0x40000063u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ -#define SDLK_APPLICATION 0x40000065u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ -#define SDLK_POWER 0x40000066u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ -#define SDLK_KP_EQUALS 0x40000067u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ -#define SDLK_F13 0x40000068u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ -#define SDLK_F14 0x40000069u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ -#define SDLK_F15 0x4000006au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ -#define SDLK_F16 0x4000006bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ -#define SDLK_F17 0x4000006cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ -#define SDLK_F18 0x4000006du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ -#define SDLK_F19 0x4000006eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ -#define SDLK_F20 0x4000006fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ -#define SDLK_F21 0x40000070u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ -#define SDLK_F22 0x40000071u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ -#define SDLK_F23 0x40000072u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ -#define SDLK_F24 0x40000073u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ -#define SDLK_EXECUTE 0x40000074u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ -#define SDLK_HELP 0x40000075u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ -#define SDLK_MENU 0x40000076u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ -#define SDLK_SELECT 0x40000077u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ -#define SDLK_STOP 0x40000078u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ -#define SDLK_AGAIN 0x40000079u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ -#define SDLK_UNDO 0x4000007au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ -#define SDLK_CUT 0x4000007bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ -#define SDLK_COPY 0x4000007cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ -#define SDLK_PASTE 0x4000007du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ -#define SDLK_FIND 0x4000007eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ -#define SDLK_MUTE 0x4000007fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ -#define SDLK_VOLUMEUP 0x40000080u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ -#define SDLK_VOLUMEDOWN 0x40000081u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ -#define SDLK_KP_COMMA 0x40000085u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ -#define SDLK_KP_EQUALSAS400 0x40000086u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ -#define SDLK_ALTERASE 0x40000099u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ -#define SDLK_SYSREQ 0x4000009au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ -#define SDLK_CANCEL 0x4000009bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ -#define SDLK_CLEAR 0x4000009cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ -#define SDLK_PRIOR 0x4000009du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ -#define SDLK_RETURN2 0x4000009eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ -#define SDLK_SEPARATOR 0x4000009fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ -#define SDLK_OUT 0x400000a0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ -#define SDLK_OPER 0x400000a1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ -#define SDLK_CLEARAGAIN 0x400000a2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ -#define SDLK_CRSEL 0x400000a3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ -#define SDLK_EXSEL 0x400000a4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ -#define SDLK_KP_00 0x400000b0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ -#define SDLK_KP_000 0x400000b1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ -#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ -#define SDLK_DECIMALSEPARATOR 0x400000b3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ -#define SDLK_CURRENCYUNIT 0x400000b4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ -#define SDLK_CURRENCYSUBUNIT 0x400000b5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ -#define SDLK_KP_LEFTPAREN 0x400000b6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ -#define SDLK_KP_RIGHTPAREN 0x400000b7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ -#define SDLK_KP_LEFTBRACE 0x400000b8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ -#define SDLK_KP_RIGHTBRACE 0x400000b9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ -#define SDLK_KP_TAB 0x400000bau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ -#define SDLK_KP_BACKSPACE 0x400000bbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ -#define SDLK_KP_A 0x400000bcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ -#define SDLK_KP_B 0x400000bdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ -#define SDLK_KP_C 0x400000beu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ -#define SDLK_KP_D 0x400000bfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ -#define SDLK_KP_E 0x400000c0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ -#define SDLK_KP_F 0x400000c1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ -#define SDLK_KP_XOR 0x400000c2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ -#define SDLK_KP_POWER 0x400000c3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ -#define SDLK_KP_PERCENT 0x400000c4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ -#define SDLK_KP_LESS 0x400000c5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ -#define SDLK_KP_GREATER 0x400000c6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ -#define SDLK_KP_AMPERSAND 0x400000c7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ -#define SDLK_KP_DBLAMPERSAND 0x400000c8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ -#define SDLK_KP_VERTICALBAR 0x400000c9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ -#define SDLK_KP_DBLVERTICALBAR 0x400000cau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ -#define SDLK_KP_COLON 0x400000cbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ -#define SDLK_KP_HASH 0x400000ccu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ -#define SDLK_KP_SPACE 0x400000cdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ -#define SDLK_KP_AT 0x400000ceu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ -#define SDLK_KP_EXCLAM 0x400000cfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ -#define SDLK_KP_MEMSTORE 0x400000d0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ -#define SDLK_KP_MEMRECALL 0x400000d1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ -#define SDLK_KP_MEMCLEAR 0x400000d2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ -#define SDLK_KP_MEMADD 0x400000d3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ -#define SDLK_KP_MEMSUBTRACT 0x400000d4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ -#define SDLK_KP_MEMMULTIPLY 0x400000d5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ -#define SDLK_KP_MEMDIVIDE 0x400000d6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ -#define SDLK_KP_PLUSMINUS 0x400000d7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ -#define SDLK_KP_CLEAR 0x400000d8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ -#define SDLK_KP_CLEARENTRY 0x400000d9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ -#define SDLK_KP_BINARY 0x400000dau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ -#define SDLK_KP_OCTAL 0x400000dbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ -#define SDLK_KP_DECIMAL 0x400000dcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ -#define SDLK_KP_HEXADECIMAL 0x400000ddu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ -#define SDLK_LCTRL 0x400000e0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ -#define SDLK_LSHIFT 0x400000e1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ -#define SDLK_LALT 0x400000e2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ -#define SDLK_LGUI 0x400000e3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ -#define SDLK_RCTRL 0x400000e4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ -#define SDLK_RSHIFT 0x400000e5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ -#define SDLK_RALT 0x400000e6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ -#define SDLK_RGUI 0x400000e7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ -#define SDLK_MODE 0x40000101u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ -#define SDLK_SLEEP 0x40000102u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ -#define SDLK_WAKE 0x40000103u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ -#define SDLK_CHANNEL_INCREMENT 0x40000104u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ -#define SDLK_CHANNEL_DECREMENT 0x40000105u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ -#define SDLK_MEDIA_PLAY 0x40000106u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ -#define SDLK_MEDIA_PAUSE 0x40000107u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ -#define SDLK_MEDIA_RECORD 0x40000108u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ -#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ -#define SDLK_MEDIA_REWIND 0x4000010au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ -#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ -#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ -#define SDLK_MEDIA_STOP 0x4000010du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ -#define SDLK_MEDIA_EJECT 0x4000010eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ -#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ -#define SDLK_MEDIA_SELECT 0x40000110u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ -#define SDLK_AC_NEW 0x40000111u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ -#define SDLK_AC_OPEN 0x40000112u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ -#define SDLK_AC_CLOSE 0x40000113u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ -#define SDLK_AC_EXIT 0x40000114u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ -#define SDLK_AC_SAVE 0x40000115u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ -#define SDLK_AC_PRINT 0x40000116u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ -#define SDLK_AC_PROPERTIES 0x40000117u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ -#define SDLK_AC_SEARCH 0x40000118u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ -#define SDLK_AC_HOME 0x40000119u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ -#define SDLK_AC_BACK 0x4000011au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ -#define SDLK_AC_FORWARD 0x4000011bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ -#define SDLK_AC_STOP 0x4000011cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ -#define SDLK_AC_REFRESH 0x4000011du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ -#define SDLK_AC_BOOKMARKS 0x4000011eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ -#define SDLK_SOFTLEFT 0x4000011fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ -#define SDLK_SOFTRIGHT 0x40000120u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ -#define SDLK_CALL 0x40000121u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ -#define SDLK_ENDCALL 0x40000122u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_UNKNOWN 0x00000000u /**< 0 */ +#define SDLK_RETURN 0x0000000du /**< '\r' */ +#define SDLK_ESCAPE 0x0000001bu /**< '\x1B' */ +#define SDLK_BACKSPACE 0x00000008u /**< '\b' */ +#define SDLK_TAB 0x00000009u /**< '\t' */ +#define SDLK_SPACE 0x00000020u /**< ' ' */ +#define SDLK_EXCLAIM 0x00000021u /**< '!' */ +#define SDLK_DBLAPOSTROPHE 0x00000022u /**< '"' */ +#define SDLK_HASH 0x00000023u /**< '#' */ +#define SDLK_DOLLAR 0x00000024u /**< '$' */ +#define SDLK_PERCENT 0x00000025u /**< '%' */ +#define SDLK_AMPERSAND 0x00000026u /**< '&' */ +#define SDLK_APOSTROPHE 0x00000027u /**< '\'' */ +#define SDLK_LEFTPAREN 0x00000028u /**< '(' */ +#define SDLK_RIGHTPAREN 0x00000029u /**< ')' */ +#define SDLK_ASTERISK 0x0000002au /**< '*' */ +#define SDLK_PLUS 0x0000002bu /**< '+' */ +#define SDLK_COMMA 0x0000002cu /**< ',' */ +#define SDLK_MINUS 0x0000002du /**< '-' */ +#define SDLK_PERIOD 0x0000002eu /**< '.' */ +#define SDLK_SLASH 0x0000002fu /**< '/' */ +#define SDLK_0 0x00000030u /**< '0' */ +#define SDLK_1 0x00000031u /**< '1' */ +#define SDLK_2 0x00000032u /**< '2' */ +#define SDLK_3 0x00000033u /**< '3' */ +#define SDLK_4 0x00000034u /**< '4' */ +#define SDLK_5 0x00000035u /**< '5' */ +#define SDLK_6 0x00000036u /**< '6' */ +#define SDLK_7 0x00000037u /**< '7' */ +#define SDLK_8 0x00000038u /**< '8' */ +#define SDLK_9 0x00000039u /**< '9' */ +#define SDLK_COLON 0x0000003au /**< ':' */ +#define SDLK_SEMICOLON 0x0000003bu /**< ';' */ +#define SDLK_LESS 0x0000003cu /**< '<' */ +#define SDLK_EQUALS 0x0000003du /**< '=' */ +#define SDLK_GREATER 0x0000003eu /**< '>' */ +#define SDLK_QUESTION 0x0000003fu /**< '?' */ +#define SDLK_AT 0x00000040u /**< '@' */ +#define SDLK_LEFTBRACKET 0x0000005bu /**< '[' */ +#define SDLK_BACKSLASH 0x0000005cu /**< '\\' */ +#define SDLK_RIGHTBRACKET 0x0000005du /**< ']' */ +#define SDLK_CARET 0x0000005eu /**< '^' */ +#define SDLK_UNDERSCORE 0x0000005fu /**< '_' */ +#define SDLK_GRAVE 0x00000060u /**< '`' */ +#define SDLK_A 0x00000061u /**< 'a' */ +#define SDLK_B 0x00000062u /**< 'b' */ +#define SDLK_C 0x00000063u /**< 'c' */ +#define SDLK_D 0x00000064u /**< 'd' */ +#define SDLK_E 0x00000065u /**< 'e' */ +#define SDLK_F 0x00000066u /**< 'f' */ +#define SDLK_G 0x00000067u /**< 'g' */ +#define SDLK_H 0x00000068u /**< 'h' */ +#define SDLK_I 0x00000069u /**< 'i' */ +#define SDLK_J 0x0000006au /**< 'j' */ +#define SDLK_K 0x0000006bu /**< 'k' */ +#define SDLK_L 0x0000006cu /**< 'l' */ +#define SDLK_M 0x0000006du /**< 'm' */ +#define SDLK_N 0x0000006eu /**< 'n' */ +#define SDLK_O 0x0000006fu /**< 'o' */ +#define SDLK_P 0x00000070u /**< 'p' */ +#define SDLK_Q 0x00000071u /**< 'q' */ +#define SDLK_R 0x00000072u /**< 'r' */ +#define SDLK_S 0x00000073u /**< 's' */ +#define SDLK_T 0x00000074u /**< 't' */ +#define SDLK_U 0x00000075u /**< 'u' */ +#define SDLK_V 0x00000076u /**< 'v' */ +#define SDLK_W 0x00000077u /**< 'w' */ +#define SDLK_X 0x00000078u /**< 'x' */ +#define SDLK_Y 0x00000079u /**< 'y' */ +#define SDLK_Z 0x0000007au /**< 'z' */ +#define SDLK_LEFTBRACE 0x0000007bu /**< '{' */ +#define SDLK_PIPE 0x0000007cu /**< '|' */ +#define SDLK_RIGHTBRACE 0x0000007du /**< '}' */ +#define SDLK_TILDE 0x0000007eu /**< '~' */ +#define SDLK_DELETE 0x0000007fu /**< '\x7F' */ +#define SDLK_PLUSMINUS 0x000000b1u /**< '\xB1' */ +#define SDLK_CAPSLOCK 0x40000039u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ +#define SDLK_F1 0x4000003au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ +#define SDLK_F2 0x4000003bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ +#define SDLK_F3 0x4000003cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ +#define SDLK_F4 0x4000003du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ +#define SDLK_F5 0x4000003eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ +#define SDLK_F6 0x4000003fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ +#define SDLK_F7 0x40000040u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ +#define SDLK_F8 0x40000041u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ +#define SDLK_F9 0x40000042u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ +#define SDLK_F10 0x40000043u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ +#define SDLK_F11 0x40000044u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ +#define SDLK_F12 0x40000045u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ +#define SDLK_PRINTSCREEN 0x40000046u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ +#define SDLK_SCROLLLOCK 0x40000047u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ +#define SDLK_PAUSE 0x40000048u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ +#define SDLK_INSERT 0x40000049u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ +#define SDLK_HOME 0x4000004au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ +#define SDLK_PAGEUP 0x4000004bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ +#define SDLK_END 0x4000004du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ +#define SDLK_PAGEDOWN 0x4000004eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ +#define SDLK_RIGHT 0x4000004fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ +#define SDLK_LEFT 0x40000050u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ +#define SDLK_DOWN 0x40000051u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ +#define SDLK_UP 0x40000052u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ +#define SDLK_NUMLOCKCLEAR 0x40000053u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ +#define SDLK_KP_DIVIDE 0x40000054u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ +#define SDLK_KP_MULTIPLY 0x40000055u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ +#define SDLK_KP_MINUS 0x40000056u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ +#define SDLK_KP_PLUS 0x40000057u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ +#define SDLK_KP_ENTER 0x40000058u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ +#define SDLK_KP_1 0x40000059u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ +#define SDLK_KP_2 0x4000005au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ +#define SDLK_KP_3 0x4000005bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ +#define SDLK_KP_4 0x4000005cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ +#define SDLK_KP_5 0x4000005du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ +#define SDLK_KP_6 0x4000005eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ +#define SDLK_KP_7 0x4000005fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ +#define SDLK_KP_8 0x40000060u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ +#define SDLK_KP_9 0x40000061u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ +#define SDLK_KP_0 0x40000062u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ +#define SDLK_KP_PERIOD 0x40000063u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ +#define SDLK_APPLICATION 0x40000065u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ +#define SDLK_POWER 0x40000066u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ +#define SDLK_KP_EQUALS 0x40000067u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ +#define SDLK_F13 0x40000068u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ +#define SDLK_F14 0x40000069u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ +#define SDLK_F15 0x4000006au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ +#define SDLK_F16 0x4000006bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ +#define SDLK_F17 0x4000006cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ +#define SDLK_F18 0x4000006du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ +#define SDLK_F19 0x4000006eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ +#define SDLK_F20 0x4000006fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ +#define SDLK_F21 0x40000070u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ +#define SDLK_F22 0x40000071u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ +#define SDLK_F23 0x40000072u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ +#define SDLK_F24 0x40000073u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ +#define SDLK_EXECUTE 0x40000074u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ +#define SDLK_HELP 0x40000075u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ +#define SDLK_MENU 0x40000076u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ +#define SDLK_SELECT 0x40000077u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ +#define SDLK_STOP 0x40000078u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ +#define SDLK_AGAIN 0x40000079u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ +#define SDLK_UNDO 0x4000007au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ +#define SDLK_CUT 0x4000007bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ +#define SDLK_COPY 0x4000007cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ +#define SDLK_PASTE 0x4000007du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ +#define SDLK_FIND 0x4000007eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ +#define SDLK_MUTE 0x4000007fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ +#define SDLK_VOLUMEUP 0x40000080u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ +#define SDLK_VOLUMEDOWN 0x40000081u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ +#define SDLK_KP_COMMA 0x40000085u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ +#define SDLK_KP_EQUALSAS400 0x40000086u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ +#define SDLK_ALTERASE 0x40000099u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ +#define SDLK_SYSREQ 0x4000009au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ +#define SDLK_CANCEL 0x4000009bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ +#define SDLK_CLEAR 0x4000009cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ +#define SDLK_PRIOR 0x4000009du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ +#define SDLK_RETURN2 0x4000009eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ +#define SDLK_SEPARATOR 0x4000009fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ +#define SDLK_OUT 0x400000a0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ +#define SDLK_OPER 0x400000a1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ +#define SDLK_CLEARAGAIN 0x400000a2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ +#define SDLK_CRSEL 0x400000a3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ +#define SDLK_EXSEL 0x400000a4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ +#define SDLK_KP_00 0x400000b0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ +#define SDLK_KP_000 0x400000b1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ +#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ +#define SDLK_DECIMALSEPARATOR 0x400000b3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ +#define SDLK_CURRENCYUNIT 0x400000b4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ +#define SDLK_CURRENCYSUBUNIT 0x400000b5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ +#define SDLK_KP_LEFTPAREN 0x400000b6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ +#define SDLK_KP_RIGHTPAREN 0x400000b7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ +#define SDLK_KP_LEFTBRACE 0x400000b8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ +#define SDLK_KP_RIGHTBRACE 0x400000b9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ +#define SDLK_KP_TAB 0x400000bau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ +#define SDLK_KP_BACKSPACE 0x400000bbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ +#define SDLK_KP_A 0x400000bcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ +#define SDLK_KP_B 0x400000bdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ +#define SDLK_KP_C 0x400000beu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ +#define SDLK_KP_D 0x400000bfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ +#define SDLK_KP_E 0x400000c0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ +#define SDLK_KP_F 0x400000c1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ +#define SDLK_KP_XOR 0x400000c2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ +#define SDLK_KP_POWER 0x400000c3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ +#define SDLK_KP_PERCENT 0x400000c4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ +#define SDLK_KP_LESS 0x400000c5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ +#define SDLK_KP_GREATER 0x400000c6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ +#define SDLK_KP_AMPERSAND 0x400000c7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ +#define SDLK_KP_DBLAMPERSAND 0x400000c8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ +#define SDLK_KP_VERTICALBAR 0x400000c9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ +#define SDLK_KP_DBLVERTICALBAR 0x400000cau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ +#define SDLK_KP_COLON 0x400000cbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ +#define SDLK_KP_HASH 0x400000ccu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ +#define SDLK_KP_SPACE 0x400000cdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ +#define SDLK_KP_AT 0x400000ceu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ +#define SDLK_KP_EXCLAM 0x400000cfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ +#define SDLK_KP_MEMSTORE 0x400000d0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ +#define SDLK_KP_MEMRECALL 0x400000d1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ +#define SDLK_KP_MEMCLEAR 0x400000d2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ +#define SDLK_KP_MEMADD 0x400000d3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ +#define SDLK_KP_MEMSUBTRACT 0x400000d4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ +#define SDLK_KP_MEMMULTIPLY 0x400000d5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ +#define SDLK_KP_MEMDIVIDE 0x400000d6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ +#define SDLK_KP_PLUSMINUS 0x400000d7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ +#define SDLK_KP_CLEAR 0x400000d8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ +#define SDLK_KP_CLEARENTRY 0x400000d9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ +#define SDLK_KP_BINARY 0x400000dau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ +#define SDLK_KP_OCTAL 0x400000dbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ +#define SDLK_KP_DECIMAL 0x400000dcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ +#define SDLK_KP_HEXADECIMAL 0x400000ddu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ +#define SDLK_LCTRL 0x400000e0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ +#define SDLK_LSHIFT 0x400000e1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ +#define SDLK_LALT 0x400000e2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ +#define SDLK_LGUI 0x400000e3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ +#define SDLK_RCTRL 0x400000e4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ +#define SDLK_RSHIFT 0x400000e5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ +#define SDLK_RALT 0x400000e6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ +#define SDLK_RGUI 0x400000e7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ +#define SDLK_MODE 0x40000101u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ +#define SDLK_SLEEP 0x40000102u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ +#define SDLK_WAKE 0x40000103u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ +#define SDLK_CHANNEL_INCREMENT 0x40000104u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ +#define SDLK_CHANNEL_DECREMENT 0x40000105u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ +#define SDLK_MEDIA_PLAY 0x40000106u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ +#define SDLK_MEDIA_PAUSE 0x40000107u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ +#define SDLK_MEDIA_RECORD 0x40000108u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ +#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ +#define SDLK_MEDIA_REWIND 0x4000010au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ +#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ +#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ +#define SDLK_MEDIA_STOP 0x4000010du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ +#define SDLK_MEDIA_EJECT 0x4000010eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ +#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ +#define SDLK_MEDIA_SELECT 0x40000110u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ +#define SDLK_AC_NEW 0x40000111u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ +#define SDLK_AC_OPEN 0x40000112u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ +#define SDLK_AC_CLOSE 0x40000113u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ +#define SDLK_AC_EXIT 0x40000114u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ +#define SDLK_AC_SAVE 0x40000115u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ +#define SDLK_AC_PRINT 0x40000116u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ +#define SDLK_AC_PROPERTIES 0x40000117u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ +#define SDLK_AC_SEARCH 0x40000118u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ +#define SDLK_AC_HOME 0x40000119u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ +#define SDLK_AC_BACK 0x4000011au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ +#define SDLK_AC_FORWARD 0x4000011bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ +#define SDLK_AC_STOP 0x4000011cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ +#define SDLK_AC_REFRESH 0x4000011du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ +#define SDLK_AC_BOOKMARKS 0x4000011eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ +#define SDLK_SOFTLEFT 0x4000011fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ +#define SDLK_SOFTRIGHT 0x40000120u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ +#define SDLK_CALL 0x40000121u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ +#define SDLK_ENDCALL 0x40000122u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_LEFT_TAB 0x20000001u /**< Extended key Left Tab */ +#define SDLK_LEVEL5_SHIFT 0x20000002u /**< Extended key Level 5 Shift */ +#define SDLK_MULTI_KEY_COMPOSE 0x20000003u /**< Extended key Multi-key Compose */ +#define SDLK_LMETA 0x20000004u /**< Extended key Left Meta */ +#define SDLK_RMETA 0x20000005u /**< Extended key Right Meta */ +#define SDLK_LHYPER 0x20000006u /**< Extended key Left Hyper */ +#define SDLK_RHYPER 0x20000007u /**< Extended key Right Hyper */ /** * Valid key modifiers (possibly OR'd together). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint16 SDL_Keymod; #define SDL_KMOD_NONE 0x0000u /**< no modifier is applicable. */ #define SDL_KMOD_LSHIFT 0x0001u /**< the left Shift key is down. */ #define SDL_KMOD_RSHIFT 0x0002u /**< the right Shift key is down. */ +#define SDL_KMOD_LEVEL5 0x0004u /**< the Level 5 Shift key is down. */ #define SDL_KMOD_LCTRL 0x0040u /**< the left Ctrl (Control) key is down. */ #define SDL_KMOD_RCTRL 0x0080u /**< the right Ctrl (Control) key is down. */ #define SDL_KMOD_LALT 0x0100u /**< the left Alt key is down. */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h index ab34a38..f8649d7 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ * * System-dependent library loading routines. * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * * Some things to keep in mind: * * - These functions only work on C function names. Other languages may have @@ -38,6 +46,11 @@ * not defined whether or not it goes into the global symbol namespace for * the application. If it does and it conflicts with symbols in your code or * other shared libraries, you will not get the results you expect. :) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that pointer after the library unloads. */ #ifndef SDL_loadso_h_ @@ -52,6 +65,17 @@ extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * @@ -59,12 +83,14 @@ extern "C" { * \returns an opaque pointer to the object handle or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -86,22 +112,29 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); * \returns a pointer to the function or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h index 85d7750..902843e 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategoryLocale * * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. */ #ifndef SDL_locale_h @@ -47,7 +53,7 @@ extern "C" { * would be "en"), and the country, if not NULL, will be an ISO-3166 country * code (so Canada would be "CA"). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPreferredLocales */ @@ -96,7 +102,7 @@ typedef struct SDL_Locale * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h index deda238..a56476c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,7 @@ /** * # CategoryLog * - * Simple log messages with priorities and categories. A message’s + * Simple log messages with priorities and categories. A message's * SDL_LogPriority signifies how important the message is. A message's * SDL_LogCategory signifies from what domain it belongs to. Every category * has a minimum priority specified: when a message belongs to that category, @@ -76,7 +76,7 @@ extern "C" { * level, the assert category is enabled at the WARN level, test is enabled at * the VERBOSE level and all other categories are enabled at the ERROR level. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogCategory { @@ -87,12 +87,11 @@ typedef enum SDL_LogCategory SDL_LOG_CATEGORY_AUDIO, SDL_LOG_CATEGORY_VIDEO, SDL_LOG_CATEGORY_RENDER, - SDL_LOG_CATEGORY_GPU, SDL_LOG_CATEGORY_INPUT, SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, SDL_LOG_CATEGORY_RESERVED2, SDL_LOG_CATEGORY_RESERVED3, SDL_LOG_CATEGORY_RESERVED4, @@ -117,17 +116,19 @@ typedef enum SDL_LogCategory /** * The predefined log priorities * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogPriority { - SDL_LOG_PRIORITY_VERBOSE = 1, + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, SDL_LOG_PRIORITY_DEBUG, SDL_LOG_PRIORITY_INFO, SDL_LOG_PRIORITY_WARN, SDL_LOG_PRIORITY_ERROR, SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES + SDL_LOG_PRIORITY_COUNT } SDL_LogPriority; @@ -136,7 +137,9 @@ typedef enum SDL_LogPriority * * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriority @@ -149,14 +152,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); * \param category the category to assign a priority to. * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetLogPriority * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriorities */ -extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, - SDL_LogPriority priority); +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); /** * Get the priority of a particular log category. @@ -164,7 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, * \param category the category to query. * \returns the SDL_LogPriority for the requested category. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriority */ @@ -175,7 +181,9 @@ extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); * * This is called by SDL_Quit(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority @@ -192,15 +200,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); * \param priority the SDL_LogPriority to modify. * \param prefix the prefix to use for that log priority, or NULL to use no * prefix. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); /** * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. @@ -209,7 +219,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \param ... additional parameters matching % tokens in the `fmt` string, if * any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LogCritical * \sa SDL_LogDebug @@ -217,11 +229,37 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * @@ -230,7 +268,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -251,7 +291,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -259,6 +301,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -272,7 +315,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -280,6 +325,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogError * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -293,7 +339,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -302,6 +350,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose */ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); @@ -314,7 +363,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -322,6 +373,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -335,7 +387,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogDebug @@ -343,6 +397,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -357,7 +412,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -365,6 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -380,7 +438,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \param fmt a printf() style message format string. * \param ap a variable argument list. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -388,6 +448,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessage + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -398,7 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, /** * The prototype for the log output callback function. * - * This function is called by SDL when there is new text to be logged. + * This function is called by SDL when there is new text to be logged. A mutex + * is held so that this function is never called by more than one thread at + * once. * * \param userdata what was passed as `userdata` to * SDL_SetLogOutputFunction(). @@ -406,10 +469,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, * \param priority the priority of the message. * \param message the message being output. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void); + /** * Get the current log output function. * @@ -418,8 +495,11 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * \param userdata a pointer filled in with the pointer that is passed to * `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_SetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata); @@ -430,8 +510,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction * \param callback an SDL_LogOutputFunction to call instead of the default. * \param userdata a pointer that is passed to `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_GetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h index de3c187..2e7a2eb 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,13 +22,29 @@ /** * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() if necessary so that it is called by SDL. * - * For details on how SDL_main works, and how to use it, please refer to: + * In order to make this consistent on all platforms, the application's main() + * should look like this: + * + * ```c + * int main(int argc, char *argv[]) + * { + * } + * ``` + * + * SDL will take care of platform specific details on how it gets called. + * + * This is also where an app can be configured to use the main callbacks, via + * the SDL_MAIN_USE_CALLBACKS macro. + * + * This is a "single-header library," which is to say that including this + * header inserts code into your program, and you should only include it once + * in most cases. SDL.h does not include this header automatically. + * + * For more information, see: * * https://wiki.libsdl.org/SDL3/README/main-functions - * - * (or docs/README-main-functions.md in the SDL source tree) */ #ifndef SDL_main_h_ @@ -39,8 +55,96 @@ #include #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Inform SDL that the app is providing an entry point instead of SDL. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide the + * proper entry point for the platform, and all the other magic details + * needed, like manually calling SDL_SetMainReady. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + */ +#define SDL_MAIN_HANDLED 1 + +/** + * Inform SDL to use the main callbacks instead of main. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide + * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and + * SDL_AppQuit. The app should not provide a `main` function in this case, and + * doing so will likely cause the build to fail. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + * \sa SDL_AppIterate + * \sa SDL_AppQuit + */ +#define SDL_MAIN_USE_CALLBACKS 1 + +/** + * Defined if the target platform offers a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if available, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_AVAILABLE + +/** + * Defined if the target platform _requires_ a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if required, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_NEEDED + +#endif + +#if defined(__has_include) + #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h") + #define SDL_PLATFORM_PRIVATE_MAIN + #endif +#endif + #ifndef SDL_MAIN_HANDLED - #ifdef SDL_PLATFORM_WIN32 + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_private.h" + + #elif defined(SDL_PLATFORM_WIN32) /* On Windows SDL provides WinMain(), which parses the command line and passes the arguments to your main function. @@ -48,20 +152,6 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_WINRT) - /* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - 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 ` - 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 - #elif defined(SDL_PLATFORM_GDK) /* On GDK, SDL provides a main function that initializes the game runtime. @@ -91,8 +181,14 @@ */ #define SDL_MAIN_NEEDED - /* We need to export SDL_main so it can be launched from Java */ - #define SDLMAIN_DECLSPEC SDL_DECLSPEC + /* As this is launched from Java, the real entry point (main() function) + is outside of the the binary built from this code. + This define makes sure that, unlike on other platforms, SDL_main.h + and SDL_main_impl.h export an `SDL_main()` function (to be called + from Java), but don't implement a native `int main(int argc, char* argv[])` + or similar. + */ + #define SDL_MAIN_EXPORTED #elif defined(SDL_PLATFORM_EMSCRIPTEN) /* On Emscripten, SDL provides a main function that converts URL @@ -129,60 +225,36 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_NGAGE) - /* - TODO: not sure if it should be SDL_MAIN_NEEDED, in SDL2 ngage had a - main implementation, but wasn't mentioned in SDL_main.h - */ - #define SDL_MAIN_AVAILABLE - #endif #endif /* SDL_MAIN_HANDLED */ -#ifndef SDLMAIN_DECLSPEC -#define SDLMAIN_DECLSPEC -#endif - -/** - * \file SDL_main.h - * - * The application's main() function must be called with C linkage, - * and should be declared like this: - * - * ```c - * #ifdef __cplusplus - * extern "C" - * #endif - * int main(int argc, char *argv[]) - * { - * } - * ``` - */ #ifdef SDL_WIKI_DOCUMENTATION_SECTION /** - * Inform SDL to use the main callbacks instead of main. + * A macro to tag a main entry point function as exported. * - * SDL does not define this macro, but will check if it is defined when - * including `SDL_main.h`. If defined, SDL will expect the app to provide - * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and - * SDL_AppQuit. The app should not provide a `main` function in this case, and - * doing so will likely cause the build to fail. + * Most platforms don't need this, and the macro will be defined to nothing. + * Some, like Android, keep the entry points in a shared library and need to + * explicitly export the symbols. * - * Please see [README/main-functions](README/main-functions), (or - * docs/README-main-functions.md in the source tree) for a more detailed - * explanation. + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. * - * \since This macro is used by the headers since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit + * \sa SDL_DECLSPEC */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif +#define SDLMAIN_DECLSPEC + +#elif defined(SDL_MAIN_EXPORTED) +/* We need to export SDL_main so it can be launched from external code, + like SDLActivity.java on Android */ +#define SDLMAIN_DECLSPEC SDL_DECLSPEC +#else +/* usually this is empty */ +#define SDLMAIN_DECLSPEC +#endif /* SDL_MAIN_EXPORTED */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main @@ -248,6 +320,8 @@ extern "C" { * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code * that reports success to the platform. * + * This function is called by SDL on the main thread. + * * \param appstate a place where the app can optionally store a pointer for * future use. * \param argc the standard ANSI C main's argc; number of elements in `argv`. @@ -256,9 +330,7 @@ extern "C" { * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppIterate * \sa SDL_AppEvent @@ -301,13 +373,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int a * SDL_AppQuit and terminates with an exit code that reports success to the * platform. * + * This function is called by SDL on the main thread. + * * \param appstate an optional pointer, provided by the app in SDL_AppInit. * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with SDL_AppEvent() + * for events not pushed on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppEvent @@ -320,15 +395,15 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a * standard "main" function, you should not supply this. * - * This function is called as needed by SDL after SDL_AppInit returns 0; It is - * called once for each new event. + * This function is called as needed by SDL after SDL_AppInit returns + * SDL_APP_CONTINUE. It is called once for each new event. * * There is (currently) no guarantee about what thread this will be called * from; whatever thread pushes an event onto SDL's queue will trigger this * function. SDL is responsible for pumping the event queue between each call * to SDL_AppIterate, so in normal operation one should only get events in a * serial fashion, but be careful if you have a thread that explicitly calls - * SDL_PushEvent. + * SDL_PushEvent. SDL itself will push events to the queue on the main thread. * * Events sent to this function are not owned by the app; if you need to save * the data, you should copy it. @@ -352,14 +427,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with + * SDL_AppIterate() or SDL_AppQuit() for events not pushed from + * the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppIterate */ -extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); /** * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -385,15 +462,19 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const * function call is the last time this pointer will be provided, so any * resources to it should be cleaned up here. * + * This function is called by SDL on the main thread. + * * \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. + * \threadsafety SDL_AppEvent() may get called concurrently with this function + * if other threads that push events are still active. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.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 */ @@ -407,7 +488,7 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate); * program completion, and small non-zero values are considered * errors. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); @@ -440,7 +521,7 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); * * \threadsafety This is the program entry point. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); @@ -453,7 +534,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); * will not be changed it is necessary to define SDL_MAIN_HANDLED before * including SDL.h. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init */ @@ -485,7 +566,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); * \threadsafety Generally this is called once, near startup, from the * process's initial thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved); @@ -512,12 +593,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func * \threadsafety It is not safe to call this anywhere except as the only * function call in SDL_main. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) /** * Register a win32 window class for SDL's use. @@ -538,12 +619,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * what is specified here. * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL * will use `GetModuleHandle(NULL)` instead. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); /** * Deregister the win32 window class from an SDL_RegisterApp call. @@ -558,23 +639,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 st * deregistered when the registration counter in SDL_RegisterApp decrements to * zero through calls to this function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ - -#ifdef SDL_PLATFORM_GDK +#endif /* defined(SDL_PLATFORM_WINDOWS) */ /** * Callback from the application to let the suspend continue. * - * \since This function is available since SDL 3.0.0. + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); -#endif /* SDL_PLATFORM_GDK */ - #ifdef __cplusplus } #endif @@ -583,29 +663,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) /* include header-only SDL_main implementations */ - #if defined(SDL_MAIN_USE_CALLBACKS) \ - || defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ - || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) \ - || defined(SDL_PLATFORM_EMSCRIPTEN) - + #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) /* platforms which main (-equivalent) can be implemented in plain C */ #include - - #elif defined(SDL_PLATFORM_WINRT) /* C++ platforms */ - #ifdef __cplusplus - #include - #else - /* Note: to get rid of the following warning, you can #define SDL_MAIN_NOIMPL before including SDL_main.h - * in your C sourcefile that contains the standard main. Do *not* use SDL_MAIN_HANDLED for that, then SDL_main won't find your main()! - */ - #ifdef _MSC_VER - #pragma message("Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C (then continue including SDL_main.h there!) and create a fresh .cpp file that only contains #include ") - #elif defined(__GNUC__) /* gcc, clang, mingw and compatible are matched by this and have #warning */ - #warning "Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C and create a fresh .cpp file that only contains #include " - #endif /* __GNUC__ */ - #endif /* __cplusplus */ - - #endif /* C++ platforms like SDL_PLATFORM_WINRT etc */ + #endif #endif #endif /* SDL_main_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h index ad122df..14ebb42 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,7 +29,7 @@ #endif /* if someone wants to include SDL_main.h but doesn't want the main handing magic, - (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first + (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first. SDL_MAIN_NOIMPL is for SDL-internal usage (only affects implementation, not definition of SDL_MAIN_AVAILABLE etc in SDL_main.h) and if the user wants to have the SDL_main implementation (from this header) in another source file @@ -64,10 +64,15 @@ #endif /* SDL_MAIN_USE_CALLBACKS */ - /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */ - #if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) + /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point, + unless the real entry point needs to be somewhere else entirely, like Android where it's in Java code */ + #if (!defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)) && !defined(SDL_MAIN_EXPORTED) - #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_impl_private.h" + + #elif defined(SDL_PLATFORM_WINDOWS) /* these defines/typedefs are needed for the WinMain() definition */ #ifndef WINAPI @@ -82,7 +87,7 @@ #if defined(_MSC_VER) && !defined(SDL_PLATFORM_GDK) /* This is where execution begins [console apps] */ - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int wmain(int argc, wchar_t *wargv[], wchar_t *wenvp) { (void)argc; @@ -107,7 +112,7 @@ extern "C" { #endif - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw) #else /* ANSI */ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw) @@ -124,83 +129,7 @@ } /* extern "C" */ #endif - /* end of SDL_PLATFORM_WIN32 and SDL_PLATFORM_GDK impls */ - - #elif defined(SDL_PLATFORM_WINRT) - - /* WinRT main based on SDL_winrt_main_NonXAML.cpp, placed in the public domain by David Ludwig 3/13/14 */ - - #include - - /* At least one file in any SDL/WinRT app appears to require compilation - with C++/CX, otherwise a Windows Metadata file won't get created, and - an APPX0702 build error can appear shortly after linking. - - The following set of preprocessor code forces this file to be compiled - as C++/CX, which appears to cause Visual C++ 2012's build tools to - create this .winmd file, and will help allow builds of SDL/WinRT apps - to proceed without error. - - If other files in an app's project enable C++/CX compilation, then it might - be possible for the .cpp file including SDL_main.h to be compiled without /ZW, - for Visual C++'s build tools to create a winmd file, and for the app to - build without APPX0702 errors. In this case, if - SDL_WINRT_METADATA_FILE_AVAILABLE is defined as a C/C++ macro, then - the #error (to force C++/CX compilation) will be disabled. - - Please note that /ZW can be specified on a file-by-file basis. To do this, - right click on the file in Visual C++, click Properties, then change the - setting through the dialog that comes up. - */ - #ifndef SDL_WINRT_METADATA_FILE_AVAILABLE - #if !defined(__cplusplus) || (!defined(__cplusplus_winrt) && _MSVC_LANG < 202002L) - #error The C++ file that includes SDL_main.h must be compiled as C++ code with /ZW, otherwise build errors due to missing .winmd files can occur. - #endif - #endif - - /* Prevent MSVC++ from warning about threading models when defining our - custom WinMain. The threading model will instead be set via a direct - call to Windows::Foundation::Initialize (rather than via an attributed - function). - - To note, this warning (C4447) does not seem to come up unless this file - is compiled with C++/CX enabled (via the /ZW compiler flag). - */ - #ifdef _MSC_VER - #pragma warning(disable : 4447) - /* Make sure the function to initialize the Windows Runtime gets linked in. */ - #pragma comment(lib, "runtimeobject.lib") - #endif - - #ifdef __cplusplus - extern "C" { - #endif - int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int) - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - #if _MSVC_LANG >= 202002L - int main(int argc, char** argv) { - return SDL_RunApp(argc, argv, SDL_main, NULL); - } - #endif - #ifdef __cplusplus - } /* extern "C" */ - #endif - - /* end of WinRT impl */ - - #elif defined(SDL_PLATFORM_NGAGE) - /* same typedef as in ngage SDKs e32def.h */ - typedef signed int TInt; - /* TODO: if it turns out that this only works when built as C++, - move SDL_PLATFORM_NGAGE into the C++ section in SDL_main.h */ - TInt E32Main() - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - - /* end of SDL_PLATFORM_NGAGE impl */ + /* end of SDL_PLATFORM_WINDOWS impls */ #else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ int main(int argc, char *argv[]) diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h index c626b22..365ae36 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryMessagebox * - * Message box support routines. + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. */ #ifndef SDL_messagebox_h_ @@ -39,11 +50,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. + * Message box flags. * * If supported will display warning icon, etc. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxFlags; @@ -56,7 +67,7 @@ typedef Uint32 SDL_MessageBoxFlags; /** * SDL_MessageBoxButtonData flags. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxButtonFlags; @@ -66,7 +77,7 @@ typedef Uint32 SDL_MessageBoxButtonFlags; /** * Individual button data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxButtonData { @@ -78,7 +89,7 @@ typedef struct SDL_MessageBoxButtonData /** * RGB value used in a message box color scheme * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColor { @@ -96,23 +107,23 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX /**< Size of the colors array of SDL_MessageBoxColorScheme. */ + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** * A set of colors to use for message box dialogs * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** * MessageBox structure containing title, text, window, etc. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxData { @@ -154,14 +165,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowSimpleMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -193,17 +204,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData * to stderr if you can. * * \param flags an SDL_MessageBoxFlags value. - * \param title uTF-8 title text. - * \param message uTF-8 message text. + * \param title UTF-8 title text. + * \param message UTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h index 7c9aece..14b1bc8 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,10 @@ * # CategoryMetal * * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. */ #ifndef SDL_metal_h_ @@ -39,7 +43,7 @@ extern "C" { /** * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_MetalView; @@ -61,7 +65,7 @@ typedef void *SDL_MetalView; * \param window the window. * \returns handle NSView or UIView. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_DestroyView * \sa SDL_Metal_GetLayer @@ -76,7 +80,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *windo * * \param view the SDL_MetalView object. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ @@ -88,7 +92,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); * \param view the SDL_MetalView object. * \returns a pointer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h index 23317e0..3dd6fcd 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -62,12 +62,12 @@ extern "C" { * * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h index 90c8560..18856e2 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,36 @@ /** * # CategoryMouse * - * SDL mouse handling. + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. */ #ifndef SDL_mouse_h_ @@ -30,6 +59,7 @@ #include #include +#include #include #include @@ -46,7 +76,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MouseID; @@ -55,14 +85,14 @@ typedef Uint32 SDL_MouseID; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Cursor SDL_Cursor; /** * Cursor types for SDL_CreateSystemCursor(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemCursor { @@ -86,13 +116,13 @@ typedef enum SDL_SystemCursor SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ - SDL_NUM_SYSTEM_CURSORS + SDL_SYSTEM_CURSOR_COUNT } SDL_SystemCursor; /** * Scroll direction types for the Scroll event * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MouseWheelDirection { @@ -109,7 +139,7 @@ typedef enum SDL_MouseWheelDirection * - Button 4: Side mouse button 1 * - Button 5: Side mouse button 2 * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetMouseState * \sa SDL_GetGlobalMouseState @@ -123,12 +153,12 @@ typedef Uint32 SDL_MouseButtonFlags; #define SDL_BUTTON_X1 4 #define SDL_BUTTON_X2 5 -#define SDL_BUTTON(X) (1u << ((X)-1)) -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) /* Function prototypes */ @@ -136,13 +166,15 @@ typedef Uint32 SDL_MouseButtonFlags; /** * Return whether a mouse is currently connected. * - * \returns SDL_TRUE if a mouse is connected, SDL_FALSE otherwise. + * \returns true if a mouse is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); /** * Get a list of currently connected mice. @@ -158,7 +190,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseNameForID * \sa SDL_HasMouse @@ -174,7 +208,9 @@ extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count); * \returns the name of the selected mouse, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ @@ -185,26 +221,39 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta * * \returns the window with mouse focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); /** - * Retrieve the current state of the mouse. + * Query SDL's cache for the synchronous mouse button state and the + * window-relative SDL-cursor position. * - * The current button state is returned as a button bitmask, which can be - * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse cursor position relative to the focus window. You can pass NULL for - * either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x the x coordinate of the mouse cursor position relative to the - * focus window. - * \param y the y coordinate of the mouse cursor position relative to the - * focus window. - * \returns a 32-bit button bitmask of the current button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the focused window. + * + * In Relative Mode, the SDL-cursor's position usually contradicts the + * platform-cursor's position as manually calculated from + * SDL_GetGlobalMouseState() and SDL_GetWindowPosition. + * + * \param x a pointer to receive the SDL-cursor's x-position from the focused + * window's top left corner, can be NULL if unused. + * \param y a pointer to receive the SDL-cursor's y-position from the focused + * window's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState * \sa SDL_GetRelativeMouseState @@ -212,51 +261,74 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y); /** - * Get the current state of the mouse in relation to the desktop. + * Query the platform for the asynchronous mouse button state and the + * desktop-relative platform-cursor position. * - * This works similarly to SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if you - * need to track the mouse outside of a specific window and SDL_CaptureMouse() - * doesn't fit your needs. For example, it could be useful if you need to - * track the mouse while dragging a window, where coordinates relative to a - * window might not be in sync at all times. + * This function immediately queries the platform for the most recent + * asynchronous state, more costly than retrieving SDL's cached state in + * SDL_GetMouseState(). * - * Note: SDL_GetMouseState() returns the mouse position as SDL understands it - * from the last pump of the event queue. This function, however, queries the - * OS for the current mouse position, and as such, might be a slightly less - * efficient function. Unless you know what you're doing and have a good - * reason to use this function, you probably want SDL_GetMouseState() instead. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the desktop. * - * \param x filled in with the current X coord relative to the desktop; can be - * NULL. - * \param y filled in with the current Y coord relative to the desktop; can be - * NULL. - * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. + * In Relative Mode, the platform-cursor's position usually contradicts the + * SDL-cursor's position as manually calculated from SDL_GetMouseState() and + * SDL_GetWindowPosition. * - * \since This function is available since SDL 3.0.0. + * This function can be useful if you need to track the mouse outside of a + * specific window and SDL_CaptureMouse() doesn't fit your needs. For example, + * it could be useful if you need to track the mouse while dragging a window, + * where coordinates relative to a window might not be in sync at all times. + * + * \param x a pointer to receive the platform-cursor's x-position from the + * desktop's top left corner, can be NULL if unused. + * \param y a pointer to receive the platform-cursor's y-position from the + * desktop's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CaptureMouse * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y); /** - * Retrieve the relative state of the mouse. + * Query SDL's cache for the synchronous mouse button state and accumulated + * mouse delta since last call. * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x a pointer filled with the last recorded x coordinate of the mouse. - * \param y a pointer filled with the last recorded y coordinate of the mouse. - * \returns a 32-bit button bitmask of the relative button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y deltas accumulated since the last call to this function + * (or since event initialization). + * + * This function is useful for reducing overhead by processing relative mouse + * inputs in one go per-frame instead of individually per-event, at the + * expense of losing the order between events within the frame (e.g. quickly + * pressing and releasing a button within the same frame). + * + * \param x a pointer to receive the x mouse delta accumulated since last + * call, can be NULL if unused. + * \param y a pointer to receive the y mouse delta accumulated since last + * call, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y); @@ -275,7 +347,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float * \param x the x coordinate within the window. * \param y the y coordinate within the window. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseGlobal */ @@ -295,14 +369,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * * \param x the x coordinate. * \param y the y coordinate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseInWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); /** * Set relative mouse mode for a window. @@ -312,31 +388,39 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * report continuous relative mouse motion even if the mouse is at the edge of * the window. * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * * This function will flush any pending mouse motion for this window. * * \param window the window to change. - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); /** * Query whether relative mouse mode is enabled for a window. * * \param window the window to query. - * \returns SDL_TRUE if relative mode is enabled for a window or SDL_FALSE - * otherwise. + * \returns true if relative mode is enabled for a window or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); /** * Capture the mouse and to track input outside an SDL window. @@ -374,15 +458,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window * * app, you can disable auto capture by setting the * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); /** * Create a cursor using the specified bitmap data and mask (in MSB format). @@ -419,7 +505,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); * \returns a new cursor with the specified parameters on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateSystemCursor @@ -450,7 +538,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data, * \returns the new cursor on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCursor * \sa SDL_CreateSystemCursor @@ -468,7 +558,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyCursor */ @@ -483,14 +575,16 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * this is desired for any reason. * * \param cursor a cursor to make active. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); /** * Get the active cursor. @@ -500,7 +594,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); * * \returns the active cursor or NULL if there is no mouse. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetCursor */ @@ -515,7 +611,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void); * \returns the default cursor on success or NULL on failuree; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); @@ -527,7 +625,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); * * \param cursor the cursor to free. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateCursor @@ -538,41 +638,47 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); /** * Show the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_HideCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); /** * Hide the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); /** * Return whether the cursor is currently being shown. * - * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the - * cursor is hidden. + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideCursor * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h index 3a7ce56..c88ec15 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,84 +25,245 @@ /** * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. */ #include +#include #include +#include -/******************************************************************************/ -/* Enable thread safety attributes only with clang. +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Enable thread safety attributes, only with clang. + * * The attributes can be safely erased when compiling with other compilers. * * To enable analysis, set these environment variables before running cmake: - * export CC=clang - * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` */ -#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ - defined(__clang__) && (!defined(SWIG)) +#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) + +#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG)) #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) #else #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ #endif +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SCOPED_CAPABILITY \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PT_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_BEFORE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_AFTER(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_GENERIC(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE_SHARED(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_EXCLUDES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_SHARED_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RETURN_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) @@ -130,7 +291,7 @@ extern "C" { * * https://en.wikipedia.org/wiki/Mutex * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Mutex SDL_Mutex; @@ -147,7 +308,7 @@ typedef struct SDL_Mutex SDL_Mutex; * \returns the initialized and unlocked mutex or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyMutex * \sa SDL_LockMutex @@ -173,7 +334,7 @@ extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); * * \param mutex the mutex to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockMutex * \sa SDL_UnlockMutex @@ -184,22 +345,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * Try to lock a mutex without blocking. * * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns SDL_FALSE immediately. + * this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. * - * This function returns SDL_TRUE if passed a NULL mutex. + * This function returns true if passed a NULL mutex. * * \param mutex the mutex to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the mutex would block. + * \returns true on success, false if the mutex would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_UnlockMutex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); /** * Unlock the mutex. @@ -213,7 +374,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ * * \param mutex the mutex to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_TryLockMutex @@ -231,7 +392,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m * * \param mutex the mutex to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateMutex */ @@ -261,7 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); * about how threads are scheduled and when they can be recursively locked. * These are documented in the other rwlock functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_RWLock SDL_RWLock; @@ -296,7 +457,7 @@ typedef struct SDL_RWLock SDL_RWLock; * \returns the initialized and unlocked read/write lock or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRWLock * \sa SDL_LockRWLockForReading @@ -336,7 +497,7 @@ extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading @@ -367,7 +528,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting @@ -379,7 +540,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Try to lock a read/write lock _for reading_ without blocking. * * This works just like SDL_LockRWLockForReading(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need access to a resource but don't want to * wait for it, and will return to it to try again later. @@ -387,24 +548,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Trying to lock for read-only access can succeed if other threads are * holding read-only locks, as this won't prevent access. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); /** * Try to lock a read/write lock _for writing_ without blocking. * * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. @@ -417,18 +578,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwl * read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock before requesting a write lock. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); /** * Unlock the read/write lock. @@ -446,7 +607,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwl * * \param rwlock the rwlock to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_LockRWLockForWriting @@ -466,7 +627,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS * * \param rwlock the rwlock to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRWLock */ @@ -492,7 +653,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); * * https://en.wikipedia.org/wiki/Semaphore_(programming) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Semaphore SDL_Semaphore; @@ -509,7 +670,7 @@ typedef struct SDL_Semaphore SDL_Semaphore; * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySemaphore * \sa SDL_SignalSemaphore @@ -528,7 +689,7 @@ extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_v * * \param sem the semaphore to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSemaphore */ @@ -546,7 +707,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * * \param sem the semaphore wait on. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore @@ -560,18 +721,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * This function checks to see if the semaphore pointed to by `sem` has a * positive value and atomically decrements the semaphore value if it does. If * the semaphore doesn't have a positive value, the function immediately - * returns SDL_FALSE. + * returns false. * * \param sem the semaphore to wait on. - * \returns SDL_TRUE if the wait succeeds, SDL_FALSE if the wait would block. + * \returns true if the wait succeeds, false if the wait would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. @@ -583,22 +744,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to wait on. * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the wait succeeds or SDL_FALSE if the wait times out. + * \returns true if the wait succeeds or false if the wait times out. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); /** * Atomically increment a semaphore's value and wake waiting threads. * * \param sem the semaphore to increment. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore @@ -612,7 +773,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to query. * \returns the current value of the semaphore. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); @@ -635,7 +796,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); * * https://en.wikipedia.org/wiki/Condition_variable * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Condition SDL_Condition; @@ -645,7 +806,7 @@ typedef struct SDL_Condition SDL_Condition; * \returns a new condition variable or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -660,7 +821,7 @@ extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); * * \param cond the condition variable to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCondition */ @@ -673,7 +834,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_WaitCondition @@ -688,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalCondition * \sa SDL_WaitCondition @@ -716,7 +877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -741,22 +902,167 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mute * \param mutex the mutex used to coordinate thread access. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the condition variable is signaled, SDL_FALSE if the - * condition is not signaled in the allotted time. + * \returns true if the condition variable is signaled, false if the condition + * is not signaled in the allotted time. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition * \sa SDL_WaitCondition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, SDL_Mutex *mutex, Sint32 timeoutMS); /* @} *//* Condition variable functions */ +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * DoQuitTasks(); + * SDL_SetInitialized(&init, false); + * } + * ``` + * + * Note that this doesn't protect any resources created during initialization, + * or guarantee that nobody is using those resources during cleanup. You + * should use other mechanisms to protect those, if that's a concern for your + * code. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h index 02c881c..c93607e 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -38,11 +38,14 @@ #ifdef SDL_ENABLE_OLD_NAMES /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer #define SDL_AtomicLock SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_UnlockSpinlock #define SDL_atomic_t SDL_AtomicInt @@ -74,6 +77,7 @@ #define SDL_NewAudioStream SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -166,14 +170,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -193,7 +196,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -304,6 +307,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -419,9 +424,15 @@ #define SDL_LogSetAllPriority SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK #define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT @@ -558,6 +569,7 @@ #define SDL_WriteLE64 SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -580,7 +592,12 @@ #define SDL_SensorUpdate SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE false #define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtok_r /* ##SDL_surface.h */ @@ -623,14 +640,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iPhoneSetEventPump SDL_SetiOSEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_CleanupTLS #define SDL_TLSGet SDL_GetTLS #define SDL_TLSSet SDL_SetTLS @@ -645,6 +661,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint @@ -661,11 +681,14 @@ #elif !defined(SDL_DISABLE_OLD_NAMES) /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer #define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock #define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt @@ -697,6 +720,7 @@ #define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -789,14 +813,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_WINDOWEVENT_RESTORED_renamed_SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_WINDOWEVENT_SHOWN_renamed_SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_WINDOWEVENT_TAKE_FOCUS_renamed_SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_eventaction_renamed_SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_CONTROLLER_AXIS_RIGHTX_renamed_SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_CONTROLLER_AXIS_RIGHTY_renamed_SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_CONTROLLER_AXIS_TRIGGERLEFT_renamed_SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -816,7 +839,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_CONTROLLER_BUTTON_INVALID_renamed_SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_CONTROLLER_BUTTON_LEFTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_CONTROLLER_BUTTON_LEFTSTICK_renamed_SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_CONTROLLER_BUTTON_MISC1_renamed_SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_CONTROLLER_BUTTON_PADDLE1_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_CONTROLLER_BUTTON_PADDLE2_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -928,6 +951,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE_renamed_SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_LINUX_DIGITAL_HATS_renamed_SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_LINUX_HAT_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_LINUX_JOYSTICK_CLASSIC_renamed_SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -1043,9 +1068,15 @@ #define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK #define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT @@ -1182,6 +1213,7 @@ #define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -1204,7 +1236,12 @@ #define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false #define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r /* ##SDL_surface.h */ @@ -1247,14 +1284,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_WinRTGetDeviceFamily_renamed_SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPathUTF8_renamed_SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback #define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS #define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS #define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS @@ -1269,6 +1305,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DeleteContext_renamed_SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLattr_renamed_SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLcontextFlag_renamed_SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLcontextReleaseFlag_renamed_SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLprofile_renamed_SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestDisplayMode_renamed_SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetDisplayOrientation_renamed_SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h index 6bdcbe0..d1b8b02 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -783,6 +783,7 @@ typedef double GLclampd; /* double precision float in [0,1] */ * Miscellaneous */ +#ifndef SDL_OPENGL_1_NO_PROTOTYPES GLAPI void GLAPIENTRY glClearIndex( GLfloat c ); GLAPI void GLAPIENTRY glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); @@ -1480,6 +1481,706 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); + +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); + +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); + +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); + +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); + +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); + +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); + +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); + +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); + +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); + +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); + +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); + +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); + +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); + +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); + +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); + +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); + +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); + + +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + + +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); + +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); + +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); + + +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ + + +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); + +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); + +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); + +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); + +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); + +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); + + +/* + * Depth Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARDEPTHPROC) ( GLclampd depth ); + +typedef void (APIENTRYP PFNGLDEPTHFUNCPROC) ( GLenum func ); + +typedef void (APIENTRYP PFNGLDEPTHMASKPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLDEPTHRANGEPROC) ( GLclampd near_val, GLclampd far_val ); + + +/* + * Accumulation Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARACCUMPROC) ( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha ); + +typedef void (APIENTRYP PFNGLACCUMPROC) ( GLenum op, GLfloat value ); + + +/* + * Transformation + */ + +typedef void (APIENTRYP PFNGLMATRIXMODEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLORTHOPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLFRUSTUMPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLVIEWPORTPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height ); + +typedef void (APIENTRYP PFNGLPUSHMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLPOPMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADIDENTITYPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLLOADMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLMULTMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLMULTMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLROTATEDPROC) ( GLdouble angle, + GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLROTATEFPROC) ( GLfloat angle, + GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLSCALEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLSCALEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLTRANSLATEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLTRANSLATEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + + +/* + * Display Lists + */ + +typedef GLboolean (APIENTRYP PFNGLISLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLDELETELISTSPROC) ( GLuint list, GLsizei range ); + +typedef GLuint (APIENTRYP PFNGLGENLISTSPROC) ( GLsizei range ); + +typedef void (APIENTRYP PFNGLNEWLISTPROC) ( GLuint list, GLenum mode ); + +typedef void (APIENTRYP PFNGLENDLISTPROC) ( void ); + +typedef void (APIENTRYP PFNGLCALLLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLCALLLISTSPROC) ( GLsizei n, GLenum type, + const GLvoid *lists ); + +typedef void (APIENTRYP PFNGLLISTBASEPROC) ( GLuint base ); + + +/* + * Drawing Functions + */ + +typedef void (APIENTRYP PFNGLBEGINPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENDPROC) ( void ); + + +typedef void (APIENTRYP PFNGLVERTEX2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLVERTEX2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLVERTEX2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLVERTEX2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLVERTEX3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLVERTEX3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLVERTEX3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLVERTEX3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLVERTEX4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLVERTEX4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLVERTEX4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLVERTEX4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLVERTEX2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLNORMAL3BPROC) ( GLbyte nx, GLbyte ny, GLbyte nz ); +typedef void (APIENTRYP PFNGLNORMAL3DPROC) ( GLdouble nx, GLdouble ny, GLdouble nz ); +typedef void (APIENTRYP PFNGLNORMAL3FPROC) ( GLfloat nx, GLfloat ny, GLfloat nz ); +typedef void (APIENTRYP PFNGLNORMAL3IPROC) ( GLint nx, GLint ny, GLint nz ); +typedef void (APIENTRYP PFNGLNORMAL3SPROC) ( GLshort nx, GLshort ny, GLshort nz ); + +typedef void (APIENTRYP PFNGLNORMAL3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLNORMAL3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLNORMAL3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLNORMAL3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLNORMAL3SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLINDEXDPROC) ( GLdouble c ); +typedef void (APIENTRYP PFNGLINDEXFPROC) ( GLfloat c ); +typedef void (APIENTRYP PFNGLINDEXIPROC) ( GLint c ); +typedef void (APIENTRYP PFNGLINDEXSPROC) ( GLshort c ); +typedef void (APIENTRYP PFNGLINDEXUBPROC) ( GLubyte c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLINDEXDVPROC) ( const GLdouble *c ); +typedef void (APIENTRYP PFNGLINDEXFVPROC) ( const GLfloat *c ); +typedef void (APIENTRYP PFNGLINDEXIVPROC) ( const GLint *c ); +typedef void (APIENTRYP PFNGLINDEXSVPROC) ( const GLshort *c ); +typedef void (APIENTRYP PFNGLINDEXUBVPROC) ( const GLubyte *c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLCOLOR3BPROC) ( GLbyte red, GLbyte green, GLbyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3DPROC) ( GLdouble red, GLdouble green, GLdouble blue ); +typedef void (APIENTRYP PFNGLCOLOR3FPROC) ( GLfloat red, GLfloat green, GLfloat blue ); +typedef void (APIENTRYP PFNGLCOLOR3IPROC) ( GLint red, GLint green, GLint blue ); +typedef void (APIENTRYP PFNGLCOLOR3SPROC) ( GLshort red, GLshort green, GLshort blue ); +typedef void (APIENTRYP PFNGLCOLOR3UBPROC) ( GLubyte red, GLubyte green, GLubyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3UIPROC) ( GLuint red, GLuint green, GLuint blue ); +typedef void (APIENTRYP PFNGLCOLOR3USPROC) ( GLushort red, GLushort green, GLushort blue ); + +typedef void (APIENTRYP PFNGLCOLOR4BPROC) ( GLbyte red, GLbyte green, + GLbyte blue, GLbyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4DPROC) ( GLdouble red, GLdouble green, + GLdouble blue, GLdouble alpha ); +typedef void (APIENTRYP PFNGLCOLOR4FPROC) ( GLfloat red, GLfloat green, + GLfloat blue, GLfloat alpha ); +typedef void (APIENTRYP PFNGLCOLOR4IPROC) ( GLint red, GLint green, + GLint blue, GLint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4SPROC) ( GLshort red, GLshort green, + GLshort blue, GLshort alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UBPROC) ( GLubyte red, GLubyte green, + GLubyte blue, GLubyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UIPROC) ( GLuint red, GLuint green, + GLuint blue, GLuint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4USPROC) ( GLushort red, GLushort green, + GLushort blue, GLushort alpha ); + + +typedef void (APIENTRYP PFNGLCOLOR3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR3SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR3UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR3USVPROC) ( const GLushort *v ); + +typedef void (APIENTRYP PFNGLCOLOR4BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR4SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR4UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR4USVPROC) ( const GLushort *v ); + + +typedef void (APIENTRYP PFNGLTEXCOORD1DPROC) ( GLdouble s ); +typedef void (APIENTRYP PFNGLTEXCOORD1FPROC) ( GLfloat s ); +typedef void (APIENTRYP PFNGLTEXCOORD1IPROC) ( GLint s ); +typedef void (APIENTRYP PFNGLTEXCOORD1SPROC) ( GLshort s ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DPROC) ( GLdouble s, GLdouble t ); +typedef void (APIENTRYP PFNGLTEXCOORD2FPROC) ( GLfloat s, GLfloat t ); +typedef void (APIENTRYP PFNGLTEXCOORD2IPROC) ( GLint s, GLint t ); +typedef void (APIENTRYP PFNGLTEXCOORD2SPROC) ( GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DPROC) ( GLdouble s, GLdouble t, GLdouble r ); +typedef void (APIENTRYP PFNGLTEXCOORD3FPROC) ( GLfloat s, GLfloat t, GLfloat r ); +typedef void (APIENTRYP PFNGLTEXCOORD3IPROC) ( GLint s, GLint t, GLint r ); +typedef void (APIENTRYP PFNGLTEXCOORD3SPROC) ( GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DPROC) ( GLdouble s, GLdouble t, GLdouble r, GLdouble q ); +typedef void (APIENTRYP PFNGLTEXCOORD4FPROC) ( GLfloat s, GLfloat t, GLfloat r, GLfloat q ); +typedef void (APIENTRYP PFNGLTEXCOORD4IPROC) ( GLint s, GLint t, GLint r, GLint q ); +typedef void (APIENTRYP PFNGLTEXCOORD4SPROC) ( GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLTEXCOORD1DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRASTERPOS2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLRASTERPOS2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLRASTERPOS2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLRASTERPOS2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLRASTERPOS3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLRASTERPOS3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLRASTERPOS3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLRASTERPOS4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLRASTERPOS4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLRASTERPOS4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLRASTERPOS2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRECTDPROC) ( GLdouble x1, GLdouble y1, GLdouble x2, GLdouble y2 ); +typedef void (APIENTRYP PFNGLRECTFPROC) ( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ); +typedef void (APIENTRYP PFNGLRECTIPROC) ( GLint x1, GLint y1, GLint x2, GLint y2 ); +typedef void (APIENTRYP PFNGLRECTSPROC) ( GLshort x1, GLshort y1, GLshort x2, GLshort y2 ); + + +typedef void (APIENTRYP PFNGLRECTDVPROC) ( const GLdouble *v1, const GLdouble *v2 ); +typedef void (APIENTRYP PFNGLRECTFVPROC) ( const GLfloat *v1, const GLfloat *v2 ); +typedef void (APIENTRYP PFNGLRECTIVPROC) ( const GLint *v1, const GLint *v2 ); +typedef void (APIENTRYP PFNGLRECTSVPROC) ( const GLshort *v1, const GLshort *v2 ); + + +/* + * Vertex Arrays (1.1) + */ + +typedef void (APIENTRYP PFNGLVERTEXPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLNORMALPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLCOLORPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLINDEXPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLTEXCOORDPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPOINTERPROC) ( GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLGETPOINTERVPROC) ( GLenum pname, GLvoid **params ); + +typedef void (APIENTRYP PFNGLARRAYELEMENTPROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLDRAWARRAYSPROC) ( GLenum mode, GLint first, GLsizei count ); + +typedef void (APIENTRYP PFNGLDRAWELEMENTSPROC) ( GLenum mode, GLsizei count, + GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLINTERLEAVEDARRAYSPROC) ( GLenum format, GLsizei stride, + const GLvoid *pointer ); + +/* + * Lighting + */ + +typedef void (APIENTRYP PFNGLSHADEMODELPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLLIGHTFPROC) ( GLenum light, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTIPROC) ( GLenum light, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTFVPROC) ( GLenum light, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTIVPROC) ( GLenum light, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETLIGHTFVPROC) ( GLenum light, GLenum pname, + GLfloat *params ); +typedef void (APIENTRYP PFNGLGETLIGHTIVPROC) ( GLenum light, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLLIGHTMODELFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTMODELIPROC) ( GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTMODELFVPROC) ( GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTMODELIVPROC) ( GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLMATERIALFPROC) ( GLenum face, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLMATERIALIPROC) ( GLenum face, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLMATERIALFVPROC) ( GLenum face, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLMATERIALIVPROC) ( GLenum face, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETMATERIALFVPROC) ( GLenum face, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETMATERIALIVPROC) ( GLenum face, GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLCOLORMATERIALPROC) ( GLenum face, GLenum mode ); + + +/* + * Raster functions + */ + +typedef void (APIENTRYP PFNGLPIXELZOOMPROC) ( GLfloat xfactor, GLfloat yfactor ); + +typedef void (APIENTRYP PFNGLPIXELSTOREFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELSTOREIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELTRANSFERFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELTRANSFERIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELMAPFVPROC) ( GLenum map, GLsizei mapsize, + const GLfloat *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUIVPROC) ( GLenum map, GLsizei mapsize, + const GLuint *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUSVPROC) ( GLenum map, GLsizei mapsize, + const GLushort *values ); + +typedef void (APIENTRYP PFNGLGETPIXELMAPFVPROC) ( GLenum map, GLfloat *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUIVPROC) ( GLenum map, GLuint *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUSVPROC) ( GLenum map, GLushort *values ); + +typedef void (APIENTRYP PFNGLBITMAPPROC) ( GLsizei width, GLsizei height, + GLfloat xorig, GLfloat yorig, + GLfloat xmove, GLfloat ymove, + const GLubyte *bitmap ); + +typedef void (APIENTRYP PFNGLREADPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLDRAWPIXELSPROC) ( GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLCOPYPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum type ); + +/* + * Stenciling + */ + +typedef void (APIENTRYP PFNGLSTENCILFUNCPROC) ( GLenum func, GLint ref, GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILOPPROC) ( GLenum fail, GLenum zfail, GLenum zpass ); + +typedef void (APIENTRYP PFNGLCLEARSTENCILPROC) ( GLint s ); + + + +/* + * Texture mapping + */ + +typedef void (APIENTRYP PFNGLTEXGENDPROC) ( GLenum coord, GLenum pname, GLdouble param ); +typedef void (APIENTRYP PFNGLTEXGENFPROC) ( GLenum coord, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXGENIPROC) ( GLenum coord, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXGENDVPROC) ( GLenum coord, GLenum pname, const GLdouble *params ); +typedef void (APIENTRYP PFNGLTEXGENFVPROC) ( GLenum coord, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXGENIVPROC) ( GLenum coord, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXGENDVPROC) ( GLenum coord, GLenum pname, GLdouble *params ); +typedef void (APIENTRYP PFNGLGETTEXGENFVPROC) ( GLenum coord, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXGENIVPROC) ( GLenum coord, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXENVFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXENVIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXENVFVPROC) ( GLenum target, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXENVIVPROC) ( GLenum target, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXENVFVPROC) ( GLenum target, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXENVIVPROC) ( GLenum target, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXPARAMETERFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXPARAMETERFVPROC) ( GLenum target, + GLenum pname, GLfloat *params); +typedef void (APIENTRYP PFNGLGETTEXPARAMETERIVPROC) ( GLenum target, + GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERFVPROC) ( GLenum target, GLint level, + GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERIVPROC) ( GLenum target, GLint level, + GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLint border, GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLGETTEXIMAGEPROC) ( GLenum target, GLint level, + GLenum format, GLenum type, + GLvoid *pixels ); + + +/* 1.1 functions */ + +typedef void (APIENTRYP PFNGLGENTEXTURESPROC) ( GLsizei n, GLuint *textures ); + +typedef void (APIENTRYP PFNGLDELETETEXTURESPROC) ( GLsizei n, const GLuint *textures); + +typedef void (APIENTRYP PFNGLBINDTEXTUREPROC) ( GLenum target, GLuint texture ); + +typedef void (APIENTRYP PFNGLPRIORITIZETEXTURESPROC) ( GLsizei n, + const GLuint *textures, + const GLclampf *priorities ); + +typedef GLboolean (APIENTRYP PFNGLARETEXTURESRESIDENTPROC) ( GLsizei n, + const GLuint *textures, + GLboolean *residences ); + +typedef GLboolean (APIENTRYP PFNGLISTEXTUREPROC) ( GLuint texture ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, + GLsizei width, GLenum format, + GLenum type, const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLsizei height, + GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint x, GLint y, + GLsizei width ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint x, GLint y, + GLsizei width, GLsizei height ); + + +/* + * Evaluators + */ + +typedef void (APIENTRYP PFNGLMAP1DPROC) ( GLenum target, GLdouble u1, GLdouble u2, + GLint stride, + GLint order, const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP1FPROC) ( GLenum target, GLfloat u1, GLfloat u2, + GLint stride, + GLint order, const GLfloat *points ); + +typedef void (APIENTRYP PFNGLMAP2DPROC) ( GLenum target, + GLdouble u1, GLdouble u2, GLint ustride, GLint uorder, + GLdouble v1, GLdouble v2, GLint vstride, GLint vorder, + const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP2FPROC) ( GLenum target, + GLfloat u1, GLfloat u2, GLint ustride, GLint uorder, + GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, + const GLfloat *points ); + +typedef void (APIENTRYP PFNGLGETMAPDVPROC) ( GLenum target, GLenum query, GLdouble *v ); +typedef void (APIENTRYP PFNGLGETMAPFVPROC) ( GLenum target, GLenum query, GLfloat *v ); +typedef void (APIENTRYP PFNGLGETMAPIVPROC) ( GLenum target, GLenum query, GLint *v ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DPROC) ( GLdouble u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FPROC) ( GLfloat u ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DPROC) ( GLdouble u, GLdouble v ); +typedef void (APIENTRYP PFNGLEVALCOORD2FPROC) ( GLfloat u, GLfloat v ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD2FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLMAPGRID1DPROC) ( GLint un, GLdouble u1, GLdouble u2 ); +typedef void (APIENTRYP PFNGLMAPGRID1FPROC) ( GLint un, GLfloat u1, GLfloat u2 ); + +typedef void (APIENTRYP PFNGLMAPGRID2DPROC) ( GLint un, GLdouble u1, GLdouble u2, + GLint vn, GLdouble v1, GLdouble v2 ); +typedef void (APIENTRYP PFNGLMAPGRID2FPROC) ( GLint un, GLfloat u1, GLfloat u2, + GLint vn, GLfloat v1, GLfloat v2 ); + +typedef void (APIENTRYP PFNGLEVALPOINT1PROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLEVALPOINT2PROC) ( GLint i, GLint j ); + +typedef void (APIENTRYP PFNGLEVALMESH1PROC) ( GLenum mode, GLint i1, GLint i2 ); + +typedef void (APIENTRYP PFNGLEVALMESH2PROC) ( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + + +/* + * Fog + */ + +typedef void (APIENTRYP PFNGLFOGFPROC) ( GLenum pname, GLfloat param ); + +typedef void (APIENTRYP PFNGLFOGIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLFOGFVPROC) ( GLenum pname, const GLfloat *params ); + +typedef void (APIENTRYP PFNGLFOGIVPROC) ( GLenum pname, const GLint *params ); + + +/* + * Selection and Feedback + */ + +typedef void (APIENTRYP PFNGLFEEDBACKBUFFERPROC) ( GLsizei size, GLenum type, GLfloat *buffer ); + +typedef void (APIENTRYP PFNGLPASSTHROUGHPROC) ( GLfloat token ); + +typedef void (APIENTRYP PFNGLSELECTBUFFERPROC) ( GLsizei size, GLuint *buffer ); + +typedef void (APIENTRYP PFNGLINITNAMESPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPUSHNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPOPNAMEPROC) ( void ); +#endif /* @@ -1528,6 +2229,8 @@ GLAPI void GLAPIENTRY glPopName( void ); #define GL_MAX_3D_TEXTURE_SIZE 0x8073 #define GL_TEXTURE_BINDING_3D 0x806A +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); @@ -1551,6 +2254,34 @@ GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, GLint y, GLsizei width, GLsizei height ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) ( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif + typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); @@ -1638,6 +2369,8 @@ typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, #define GL_BLEND_COLOR 0x8005 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, GLsizei width, GLenum format, GLenum type, const GLvoid *table ); @@ -1746,6 +2479,119 @@ GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +typedef void (APIENTRYP PFNGLCOLORSUBTABLEPROC) ( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERIVPROC) (GLenum target, GLenum pname, + const GLint *params); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERFVPROC) (GLenum target, GLenum pname, + const GLfloat *params); + +typedef void (APIENTRYP PFNGLCOPYCOLORSUBTABLEPROC) ( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLBLENDEQUATIONPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLBLENDCOLORPROC) ( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLHISTOGRAMPROC) ( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETHISTOGRAMPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLMINMAXPROC) ( GLenum target, GLenum internalformat, + GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETMINMAXPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETMINMAXPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFPROC) ( GLenum target, GLenum pname, + GLfloat params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIPROC) ( GLenum target, GLenum pname, + GLint params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLSEPARABLEFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +typedef void (APIENTRYP PFNGLGETSEPARABLEFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif + @@ -1858,6 +2704,8 @@ GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, /* texture_border_clamp */ #define GL_CLAMP_TO_BORDER 0x812D +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTexture( GLenum texture ); GLAPI void GLAPIENTRY glClientActiveTexture( GLenum texture ); @@ -1951,6 +2799,104 @@ GLAPI void GLAPIENTRY glMultTransposeMatrixf( const GLfloat m[16] ); GLAPI void GLAPIENTRY glSampleCoverage( GLclampf value, GLboolean invert ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE1DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE2DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE3DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) ( GLenum target, GLint lod, GLvoid *img ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DPROC) ( GLenum target, GLdouble s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FPROC) ( GLenum target, GLfloat s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IPROC) ( GLenum target, GLint s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SPROC) ( GLenum target, GLshort s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DPROC) ( GLenum target, GLdouble s, GLdouble t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FPROC) ( GLenum target, GLfloat s, GLfloat t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IPROC) ( GLenum target, GLint s, GLint t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SPROC) ( GLenum target, GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IPROC) ( GLenum target, GLint s, GLint t, GLint r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IPROC) ( GLenum target, GLint s, GLint t, GLint r, GLint q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVPROC) ( GLenum target, const GLshort *v ); + + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) ( GLclampf value, GLboolean invert ); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) (GLenum texture); typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) (GLclampf value, GLboolean invert); @@ -2006,6 +2952,8 @@ typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) (GLenum target, GLint le #define GL_CLIENT_ACTIVE_TEXTURE_ARB 0x84E1 #define GL_MAX_TEXTURE_UNITS_ARB 0x84E2 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glClientActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glMultiTexCoord1dARB(GLenum target, GLdouble s); @@ -2041,6 +2989,46 @@ GLAPI void GLAPIENTRY glMultiTexCoord4ivARB(GLenum target, const GLint *v); GLAPI void GLAPIENTRY glMultiTexCoord4sARB(GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); GLAPI void GLAPIENTRY glMultiTexCoord4svARB(GLenum target, const GLshort *v); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FARBPROC) (GLenum target, GLfloat s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IARBPROC) (GLenum target, GLint s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SARBPROC) (GLenum target, GLshort s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DARBPROC) (GLenum target, GLdouble s, GLdouble t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FARBPROC) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IARBPROC) (GLenum target, GLint s, GLint t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SARBPROC) (GLenum target, GLshort s, GLshort t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IARBPROC) (GLenum target, GLint s, GLint t, GLint r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IARBPROC) (GLenum target, GLint s, GLint t, GLint r, GLint q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLshort *v); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h index bde4d74..4fb9a4b 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h index ba19601..365898a 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h index cda4f0f..5182eeb 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -39,7 +39,9 @@ #ifndef SDL_pen_h_ #define SDL_pen_h_ -#include +#include +#include +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -55,24 +57,39 @@ extern "C" { * consistent as long as SDL can recognize a tool to be the same pen; but if a * pen physically leaves the area and returns, it might get a new ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenID; +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + /** * Pen input flags, as reported by various pen events' `pen_state` field. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenInputFlags; -#define SDL_PEN_INPUT_DOWN (1u << 0) /**< & to see if pen is pressed down */ -#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< & to see if button 1 is pressed */ -#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< & to see if button 2 is pressed */ -#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< & to see if button 3 is pressed */ -#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< & to see if button 4 is pressed */ -#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< & to see if button 5 is pressed */ -#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< & to see if eraser tip is used */ + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ /** * Pen axis indices. @@ -87,20 +104,18 @@ typedef Uint32 SDL_PenInputFlags; * * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PenAxis { SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ - SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). - The physical max/min tilt may be smaller than -90.0 / 90.0, check SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). - The physical max/min tilt may be smaller than -90.0 / 90.0 check SDL_PenCapabilityInfo */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ - SDL_PEN_NUM_AXES /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ } SDL_PenAxis; /* Ends C function definitions when using C++ */ @@ -110,4 +125,3 @@ typedef enum SDL_PenAxis #endif /* SDL_pen_h_ */ -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h index 3825dd5..b6f38ac 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,59 @@ /** * # CategoryPixels * - * Pixel management. + * SDL offers facilities for pixel management. + * + * Largely these facilities deal with pixel _format_: what does this set of + * bits represent? + * + * If you mostly want to think of a pixel as some combination of red, green, + * blue, and maybe alpha intensities, this is all pretty straightforward, and + * in many cases, is enough information to build a perfectly fine game. + * + * However, the actual definition of a pixel is more complex than that: + * + * Pixels are a representation of a color in a particular color space. + * + * The first characteristic of a color space is the color type. SDL + * understands two different color types, RGB and YCbCr, or in SDL also + * referred to as YUV. + * + * RGB colors consist of red, green, and blue channels of color that are added + * together to represent the colors we see on the screen. + * + * https://en.wikipedia.org/wiki/RGB_color_model + * + * YCbCr colors represent colors as a Y luma brightness component and red and + * blue chroma color offsets. This color representation takes advantage of the + * fact that the human eye is more sensitive to brightness than the color in + * an image. The Cb and Cr components are often compressed and have lower + * resolution than the luma component. + * + * https://en.wikipedia.org/wiki/YCbCr + * + * When the color information in YCbCr is compressed, the Y pixels are left at + * full resolution and each Cr and Cb pixel represents an average of the color + * information in a block of Y pixels. The chroma location determines where in + * that block of pixels the color information is coming from. + * + * The color range defines how much of the pixel to use when converting a + * pixel into a color on the display. When the full color range is used, the + * entire numeric range of the pixel bits is significant. When narrow color + * range is used, for historical reasons, the pixel uses only a portion of the + * numeric range to represent colors. + * + * The color primaries and white point are a definition of the colors in the + * color space relative to the standard XYZ color space. + * + * https://en.wikipedia.org/wiki/CIE_1931_color_space + * + * The transfer characteristic, or opto-electrical transfer function (OETF), + * is the way a color is converted from mathematically linear space into a + * non-linear output signals. + * + * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics + * + * The matrix coefficients are used to convert between YCbCr and RGB colors. */ #ifndef SDL_pixels_h_ @@ -41,22 +93,44 @@ extern "C" { /** * A fully opaque 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_TRANSPARENT */ #define SDL_ALPHA_OPAQUE 255 +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + /** * A fully transparent 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_OPAQUE */ #define SDL_ALPHA_TRANSPARENT 0 -/** Pixel type. */ +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, @@ -75,7 +149,11 @@ typedef enum SDL_PixelType SDL_PIXELTYPE_INDEX2 } SDL_PixelType; -/** Bitmap pixel order, high bit -> low bit. */ +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, @@ -83,7 +161,11 @@ typedef enum SDL_BitmapOrder SDL_BITMAPORDER_1234 } SDL_BitmapOrder; -/** Packed component order, high bit -> low bit. */ +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, @@ -97,7 +179,11 @@ typedef enum SDL_PackedOrder SDL_PACKEDORDER_BGRA } SDL_PackedOrder; -/** Array component order, low byte -> high byte. */ +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, @@ -109,7 +195,11 @@ typedef enum SDL_ArrayOrder SDL_ARRAYORDER_ABGR } SDL_ArrayOrder; -/** Packed component layout. */ +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, @@ -123,25 +213,172 @@ typedef enum SDL_PackedLayout SDL_PACKEDLAYOUT_1010102 } SDL_PackedLayout; +/** + * A macro for defining custom FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_YV12 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') + * ``` + * + * \param A the first character of the FourCC code. + * \param B the second character of the FourCC code. + * \param C the third character of the FourCC code. + * \param D the fourth character of the FourCC code. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) +/** + * A macro for defining custom non-FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) + * ``` + * + * \param type the type of the new format, probably a SDL_PixelType value. + * \param order the order of the new format, probably a SDL_BitmapOrder, + * SDL_PackedOrder, or SDL_ArrayOrder value. + * \param layout the layout of the new format, probably an SDL_PackedLayout + * value or zero. + * \param bits the number of bits per pixel of the new format. + * \param bytes the number of bytes per pixel of the new format. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ ((bits) << 8) | ((bytes) << 0)) -#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) -#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) -#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) -#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) -#define SDL_BITSPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU) || \ - ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF)) +/** + * A macro to retrieve the flags of an SDL_PixelFormat. + * + * This macro is generally not needed directly by an app, which should use + * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. + * + * \param format an SDL_PixelFormat to check. + * \returns the flags of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) +/** + * A macro to retrieve the type of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PixelType enumeration. + * + * \param format an SDL_PixelFormat to check. + * \returns the type of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) + +/** + * A macro to retrieve the order of an SDL_PixelFormat. + * + * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or + * SDL_ArrayOrder enumerations, depending on the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the order of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) + +/** + * A macro to retrieve the layout of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PackedLayout enumeration, or zero if a + * layout doesn't make sense for the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the layout of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) + +/** + * A macro to determine an SDL_PixelFormat's bits per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats will report zero here, as it rarely makes sense to measure + * them per-pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bits-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTESPERPIXEL + */ +#define SDL_BITSPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) + +/** + * A macro to determine an SDL_PixelFormat's bytes per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats do their best here, but many of them don't have a meaningful + * measurement of bytes per pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bytes-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BITSPERPIXEL + */ +#define SDL_BYTESPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? \ + ((((format) == SDL_PIXELFORMAT_YUY2) || \ + ((format) == SDL_PIXELFORMAT_UYVY) || \ + ((format) == SDL_PIXELFORMAT_YVYU) || \ + ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) + + +/** + * A macro to determine if an SDL_PixelFormat is an indexed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is indexed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -149,12 +386,38 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) +/** + * A macro to determine if an SDL_PixelFormat is a packed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is packed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_PACKED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) +/** + * A macro to determine if an SDL_PixelFormat is an array format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is an array, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -163,25 +426,84 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -#define SDL_ISPIXELFORMAT_ALPHA(format) \ - ((SDL_ISPIXELFORMAT_PACKED(format) && \ - ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))) - +/** + * A macro to determine if an SDL_PixelFormat is a 10-bit format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_10BIT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) +/** + * A macro to determine if an SDL_PixelFormat is a floating point format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ -#define SDL_ISPIXELFORMAT_FOURCC(format) \ +/** + * A macro to determine if an SDL_PixelFormat has an alpha channel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_ALPHA(format) \ + ((SDL_ISPIXELFORMAT_PACKED(format) && \ + ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ + (SDL_ISPIXELFORMAT_ARRAY(format) && \ + ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) + + +/** + * A macro to determine if an SDL_PixelFormat is a "FourCC" format. + * + * This covers custom and other unusual formats. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this enum, update SDL_GetPixelFormatName() */ @@ -221,7 +543,7 @@ typedef enum SDL_PackedLayout * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for * RGBA8888 on big-endian CPUs. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PixelFormat { @@ -351,59 +673,35 @@ typedef enum SDL_PixelFormat /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ - SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif } SDL_PixelFormat; -/* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 -#else -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888 -#endif - -/** - * Pixels are a representation of a color in a particular color space. - * - * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV. - * - * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen. - * https://en.wikipedia.org/wiki/RGB_color_model - * - * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component. - * https://en.wikipedia.org/wiki/YCbCr - * - * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from. - * - * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors. - * - * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space. - * https://en.wikipedia.org/wiki/CIE_1931_color_space - * - * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals. - * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics - * - * The matrix coefficients are used to convert between YCbCr and RGB colors. - */ - /** * Colorspace color type. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorType { @@ -416,7 +714,7 @@ typedef enum SDL_ColorType * Colorspace color range, as described by * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorRange { @@ -429,7 +727,7 @@ typedef enum SDL_ColorRange * Colorspace color primaries, as described by * https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorPrimaries { @@ -454,7 +752,7 @@ typedef enum SDL_ColorPrimaries * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TransferCharacteristics { @@ -484,7 +782,7 @@ typedef enum SDL_TransferCharacteristics * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MatrixCoefficients { @@ -508,7 +806,7 @@ typedef enum SDL_MatrixCoefficients /** * Colorspace chroma sample location. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ChromaLocation { @@ -520,22 +818,177 @@ typedef enum SDL_ChromaLocation /* Colorspace definition */ + +/** + * A macro for defining custom SDL_Colorspace formats. + * + * For example, defining SDL_COLORSPACE_SRGB looks like this: + * + * ```c + * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + * SDL_COLOR_RANGE_FULL, + * SDL_COLOR_PRIMARIES_BT709, + * SDL_TRANSFER_CHARACTERISTICS_SRGB, + * SDL_MATRIX_COEFFICIENTS_IDENTITY, + * SDL_CHROMA_LOCATION_NONE) + * ``` + * + * \param type the type of the new format, probably an SDL_ColorType value. + * \param range the range of the new format, probably a SDL_ColorRange value. + * \param primaries the primaries of the new format, probably an + * SDL_ColorPrimaries value. + * \param transfer the transfer characteristics of the new format, probably an + * SDL_TransferCharacteristics value. + * \param matrix the matrix coefficients of the new format, probably an + * SDL_MatrixCoefficients value. + * \param chroma the chroma sample location of the new format, probably an + * SDL_ChromaLocation value. + * \returns a format value in the style of SDL_Colorspace. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) -#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F) -#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F) -#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F) -#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) -#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) -#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F) +/** + * A macro to retrieve the type of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorType for `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) -#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) -#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) -#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) -#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) -#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) +/** + * A macro to retrieve the range of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorRange of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) + +/** + * A macro to retrieve the chroma sample location of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ChromaLocation of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) + +/** + * A macro to retrieve the primaries of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorPrimaries of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) + +/** + * A macro to retrieve the transfer characteristics of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_TransferCharacteristics of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) + +/** + * A macro to retrieve the matrix coefficients of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_MatrixCoefficients of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) + +/** + * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix + * coefficients. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT601 or BT470BG, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) + +/** + * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) + +/** + * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix + * coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT2020_NCL, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) + +/** + * A macro to determine if an SDL_Colorspace has a limited range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if limited range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) + +/** + * A macro to determine if an SDL_Colorspace has a full range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if full range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. @@ -544,7 +997,7 @@ typedef enum SDL_ChromaLocation * function, etc.), this is not an exhaustive list, but rather a * representative sample of the kinds of colorspaces supported in SDL. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_ColorPrimaries * \sa SDL_ColorRange @@ -631,7 +1084,7 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ - SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, SDL_COLOR_RANGE_FULL, SDL_COLOR_PRIMARIES_BT2020, @@ -639,15 +1092,10 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ } SDL_Colorspace; - -/* The default colorspace for RGB surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB - -/* The default colorspace for YUV surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG - /** * A structure that represents a color as RGBA components. * @@ -656,7 +1104,7 @@ typedef enum SDL_Colorspace * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Color { @@ -670,7 +1118,7 @@ typedef struct SDL_Color * The bits of this structure can be directly reinterpreted as a float-packed * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_FColor { @@ -683,7 +1131,7 @@ typedef struct SDL_FColor /** * A set of indexed colors representing a palette. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -698,7 +1146,7 @@ typedef struct SDL_Palette /** * Details about the format of a pixel. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PixelFormatDetails { @@ -729,7 +1177,7 @@ typedef struct SDL_PixelFormatDetails * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); @@ -742,16 +1190,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * \param Gmask a pointer filled in with the green mask for the format. * \param Bmask a pointer filled in with the blue mask for the format. * \param Amask a pointer filled in with the alpha mask for the format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatForMasks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); /** * Convert a bpp value and RGBA masks to an enumerated pixel format. @@ -769,7 +1217,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMasksForPixelFormat */ @@ -788,7 +1236,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); @@ -804,7 +1252,7 @@ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDet * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyPalette * \sa SDL_SetPaletteColors @@ -819,15 +1267,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); * \param colors an array of SDL_Color structures to copy into the palette. * \param firstcolor the index of the first palette entry to modify. * \param ncolors the number of entries to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); /** * Free a palette created with SDL_CreatePalette(). @@ -837,7 +1285,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette */ @@ -872,7 +1320,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB @@ -911,7 +1359,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -939,7 +1387,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -971,7 +1419,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h index bfdfa3a..e40f009 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,7 +51,7 @@ extern "C" { * \returns the name of the platform. If the correct platform name is not * available, returns a string beginning with the text "Unknown". * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h index e7f91cf..7e9a0a9 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,180 +29,450 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 -#endif -#ifdef __NGAGE__ -#define SDL_PLATFORM_NGAGE 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ -#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif defined(HAVE_WINAPIFAMILY_H) && HAVE_WINAPIFAMILY_H + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT -#define SDL_PLATFORM_WINRT 1 +#error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h index 1fdef78..4056ce3 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,15 @@ * # CategoryPower * * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ #include @@ -42,7 +51,7 @@ extern "C" { * * These are results returned by SDL_GetPowerInfo(). * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PowerState { @@ -80,7 +89,7 @@ typedef enum SDL_PowerState * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_process.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_process.h new file mode 100644 index 0000000..2cc7739 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_process.h @@ -0,0 +1,430 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used + * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set + * to `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value + * describing where standard error for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h index c3a2c82..1f47d5f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h @@ -1,6 +1,6 @@ /* - Simple DiretMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -61,14 +61,14 @@ extern "C" { /** * SDL properties ID * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PropertiesID; /** * SDL property type * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PropertyType { @@ -86,7 +86,7 @@ typedef enum SDL_PropertyType * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); @@ -100,7 +100,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyProperties */ @@ -116,14 +116,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); * * \param src the properties to copy. * \param dst the destination properties. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** * Lock a group of properties. @@ -138,16 +138,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SD * thread. * * \param props the properties to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockProperties */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** * Unlock a group of properties. @@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockProperties */ @@ -180,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); * \threadsafety This callback may fire without any locks held; if this is a * concern, the app should provide its own locking. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetPointerPropertyWithCleanup */ @@ -204,18 +204,18 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \param cleanup the function to call when this property is deleted, or NULL * if no cleanup is necessary. * \param userdata a pointer that is passed to the cleanup function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_SetPointerProperty * \sa SDL_CleanupPropertyCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); /** * Set a pointer property in a group of properties. @@ -223,12 +223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_HasProperty @@ -238,7 +238,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \sa SDL_SetPointerPropertyWithCleanup * \sa SDL_SetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); /** * Set a string property in a group of properties. @@ -249,16 +249,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID pro * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** * Set an integer property in a group of properties. @@ -266,16 +266,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumberProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** * Set a floating point property in a group of properties. @@ -283,16 +283,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetFloatProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** * Set a boolean property in a group of properties. @@ -300,31 +300,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); /** * Return whether a property exists in a group of properties. * * \param props the properties to query. * \param name the name of the property to query. - * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. + * \returns true if the property exists, or false if it doesn't. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** * Get the type of a property in a group of properties. @@ -336,7 +336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasProperty */ @@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty * \sa SDL_GetFloatProperty @@ -391,7 +391,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -413,7 +413,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -435,7 +435,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -457,27 +457,27 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty * \sa SDL_SetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); /** * Clear a property from a group of properties. * * \param props the properties to modify. * \param name the name of the property to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); /** * A callback used to enumerate all the properties in a group of properties. @@ -492,7 +492,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, c * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this * callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EnumerateProperties */ @@ -507,14 +507,14 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop * \param props the properties to query. * \param callback the function to call for each property. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** * Destroy a group of properties. @@ -528,7 +528,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID pr * locked or other threads might be setting or getting values * from these properties. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h index ea97df9..8998de6 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,7 +23,7 @@ * # CategoryRect * * Some helper functions for managing rectangles and 2D points, in both - * interger and floating point versions. + * integer and floating point versions. */ #ifndef SDL_rect_h_ @@ -41,7 +41,7 @@ extern "C" { /** * The structure that defines a point (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect @@ -55,7 +55,7 @@ typedef struct SDL_Point /** * The structure that defines a point (using floating point values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat @@ -70,7 +70,7 @@ typedef struct SDL_FPoint /** * A rectangle, with the origin at the upper left (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmpty * \sa SDL_RectsEqual @@ -91,7 +91,7 @@ typedef struct SDL_Rect * A rectangle, with the origin at the upper left (using floating point * values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -121,7 +121,7 @@ typedef struct SDL_FRect * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) { @@ -146,16 +146,16 @@ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) { return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; } /** @@ -170,15 +170,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) { - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; } /** @@ -194,51 +194,51 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) { return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; + (a->w == b->w) && (a->h == b->h)) ? true : false; } /** * Determine whether two rectangles intersect. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); /** * Calculate the intersection of two rectangles. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate the union of two rectangles. @@ -247,12 +247,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate a minimal rectangle enclosing a set of points. @@ -266,12 +266,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const S * \param clip an SDL_Rect used for clipping or NULL to enclose all points. * \param result an SDL_Rect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); /** * Calculate the intersection of a rectangle and line segment. @@ -287,11 +287,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); /* SDL_FRect versions... */ @@ -311,16 +311,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Re * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) { return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && - (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; } /** @@ -335,15 +335,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) { - return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; } /** @@ -363,22 +363,22 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * \param a the first rectangle to test. * \param b the second rectangle to test. * \param epsilon the epsilon value for comparison. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualFloat */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) { return (a && b && ((a == b) || ((SDL_fabsf(a->x - b->x) <= epsilon) && (SDL_fabsf(a->y - b->y) <= epsilon) && (SDL_fabsf(a->w - b->w) <= epsilon) && (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; + ? true : false; } /** @@ -398,15 +398,15 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualEpsilon */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) { return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); } @@ -414,34 +414,34 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec /** * Determine whether two rectangles intersect with float precision. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); /** * Calculate the intersection of two rectangles with float precision. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersectionFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate the union of two rectangles with float precision. @@ -450,12 +450,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate a minimal rectangle enclosing a set of points with float @@ -470,12 +470,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, c * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); /** * Calculate the intersection of a rectangle and line segment with float @@ -492,11 +492,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h index 706308c..891e994 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -40,8 +40,8 @@ * * This API is designed to accelerate simple 2D operations. You may want more * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. + * should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the + * many good 3D engines. * * These functions must be called from the main thread. See this bug for * details: https://github.com/libsdl-org/SDL/issues/986 @@ -51,10 +51,13 @@ #define SDL_render_h_ #include +#include #include #include +#include #include #include +#include #include #include @@ -66,14 +69,14 @@ extern "C" { /** * The name of the software renderer. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_SOFTWARE_RENDERER "software" /** * Vertex structure. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Vertex { @@ -85,7 +88,7 @@ typedef struct SDL_Vertex /** * The access pattern allowed for a texture. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TextureAccess { @@ -97,7 +100,7 @@ typedef enum SDL_TextureAccess /** * How the logical size is mapped to the output. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_RendererLogicalPresentation { @@ -111,15 +114,32 @@ typedef enum SDL_RendererLogicalPresentation /** * A structure representing rendering state * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Renderer SDL_Renderer; +#ifndef SDL_INTERNAL + /** * An efficient driver-specific representation of pixel data * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ @@ -135,7 +155,9 @@ typedef struct SDL_Texture SDL_Texture; * * \returns the number of built in render drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_GetRenderDriver @@ -158,7 +180,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * \returns the name of the rendering driver at the requested index, or NULL * if an invalid index was specified. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumRenderDrivers */ @@ -174,36 +198,43 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * SDL_CreateWindow()). * \param window a pointer filled with the window, or NULL on error. * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); /** * Create a 2D rendering context for a window. * * If you want a specific renderer, you can specify its name here. A list of - * available renderers can be obtained by calling SDL_GetRenderDriver multiple - * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't - * need a specific renderer, specify NULL and SDL will attempt to choose the - * best option for you, based on what is available on the user's system. + * available renderers can be obtained by calling SDL_GetRenderDriver() + * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you + * don't need a specific renderer, specify NULL and SDL will attempt to choose + * the best option for you, based on what is available on the user's system. + * + * If `name` is a comma-separated list, SDL will try each name, in the order + * listed, until one succeeds or all of them fail. * * By default the rendering size matches the window size in pixels, but you * can call SDL_SetRenderLogicalPresentation() to change the content size and * scaling options. * * \param window the window where rendering is displayed. - * \param name the name of the rendering driver to initialize, or NULL to - * initialize the first one supporting the requested flags. + * \param name the name of the rendering driver to initialize, or NULL to let + * SDL choose one. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRendererWithProperties * \sa SDL_CreateSoftwareRenderer @@ -225,7 +256,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * displayed, required if this isn't a software renderer using a surface * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering * is displayed, if you want a software renderer without a window - * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace + * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace * value describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and @@ -255,7 +286,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateRenderer @@ -290,7 +323,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRenderer */ @@ -303,7 +338,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surfac * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); @@ -314,7 +351,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); @@ -325,7 +364,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende * \returns the name of the selected renderer, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateRendererWithProperties @@ -348,21 +389,21 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN, * representing the available texture formats for this renderer. - * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with * HDR enabled. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is * automatically multiplied into the color scale. This property can change - * dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range * that can be displayed, in terms of the SDR white point. When HDR is not * enabled, this will be 1.0. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * * With the direct3d renderer: * @@ -403,11 +444,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * swapchain images, or potential frames in flight, used by the Vulkan * renderer * + * With the gpu renderer: + * + * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with + * the renderer + * * \param renderer the rendering context. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); @@ -434,6 +482,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende #define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count" +#define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device" /** * Get the output size in pixels of a rendering context. @@ -444,14 +493,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \param renderer the rendering context. * \param w a pointer filled in with the width in pixels. * \param h a pointer filled in with the height in pixels. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Get the current output size in pixels of a rendering context. @@ -464,28 +515,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *rende * \param renderer the rendering context. * \param w a pointer filled in with the current width. * \param h a pointer filled in with the current height. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Create a texture for a rendering context. * + * The contents of a texture when first created are not defined. + * * \param renderer the rendering context. * \param format one of the enumerated values in SDL_PixelFormat. * \param access one of the enumerated values in SDL_TextureAccess. * \param w the width of the texture in pixels. * \param h the height of the texture in pixels. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTextureFromSurface * \sa SDL_CreateTextureWithProperties @@ -513,7 +569,9 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureWithProperties @@ -526,7 +584,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * These are the supported properties: * - * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for @@ -617,11 +675,12 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * \param renderer the rendering context. * \param props the properties to use. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateTexture @@ -661,7 +720,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * The following read-only properties are provided by SDL: * - * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing + * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing * the texture colorspace. * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in * SDL_PixelFormat. @@ -701,14 +760,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * With the vulkan renderer: * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_POINTER`: the VkImage associated with - * the texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_U_POINTER`: the VkImage associated with - * the U plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_V_POINTER`: the VkImage associated with - * the V plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_UV_POINTER`: the VkImage associated with - * the UV plane of a NV12/NV21 texture + * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the + * texture * * With the opengl renderer: * @@ -740,16 +793,13 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc) * - * With the vulkan renderer: - * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the - * texture - * * \param texture the texture to query. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); @@ -789,7 +839,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Textur * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture); @@ -801,12 +851,14 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This * argument can be NULL if you don't need this information. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); /** * Set an additional color value multiplied into render copy operations. @@ -818,22 +870,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, fl * `srcC = srcC * (color / 255)` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); /** @@ -846,22 +900,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture * `srcC = srcC * color` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); /** @@ -871,16 +927,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *te * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); /** * Get the additional color value multiplied into render copy operations. @@ -889,16 +947,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); /** * Set an additional alpha value multiplied into render copy operations. @@ -909,20 +969,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *te * `srcA = srcA * (alpha / 255)` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); /** * Set an additional alpha value multiplied into render copy operations. @@ -933,83 +995,93 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture * `srcA = srcA * alpha` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); /** * Set the blend mode for a texture, used by SDL_RenderTexture(). * * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. + * and this function returns false. * * \param texture the texture to update. * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); /** * Get the blend mode used for texture copy operations. * * \param texture the texture to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); /** * Set the scale mode used for texture scale operations. @@ -1020,28 +1092,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *textur * * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); /** * Get the scale mode used for texture scale operations. * * \param texture the texture to query. * \param scaleMode a pointer filled in with the current scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); /** * Update the given texture rectangle with new pixel data. @@ -1063,17 +1139,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *textur * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding * between lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture * \sa SDL_UpdateNVTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); /** * Update a rectangle within a planar YV12 or IYUV texture with new pixel @@ -1095,15 +1173,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, con * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateNVTexture * \sa SDL_UpdateTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, @@ -1125,15 +1205,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \param UVplane the raw pixel data for the UV plane. * \param UVpitch the number of bytes between rows of pixel data for the UV * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch); @@ -1157,16 +1239,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the * pitch is the length of one row in bytes. - * \returns SDL_TRUE on success or SDL_FALSE if the texture is not valid or - * was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. + * \returns true on success or false if the texture is not valid or was not + * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTextureToSurface * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch); @@ -1192,17 +1276,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** * Unlock a texture, uploading the changes to video memory, if needed. @@ -1217,7 +1303,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *textu * * \param texture a texture locked by SDL_LockTexture(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture */ @@ -1234,14 +1322,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderTarget */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** * Get the current render target. @@ -1252,7 +1342,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderTarget */ @@ -1261,13 +1353,23 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend /** * Set a device independent resolution and presentation mode for rendering. * - * This function sets the width and height of the logical rendering output. A - * render target is created at the specified size and used for rendering and - * then copied to the output during presentation. + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the window is always the requested dimensions, + * scaling to the actual window resolution as necessary. + * + * This can be useful for games that expect a fixed size, but would like to + * scale the output to whatever is available, regardless of how a user resizes + * a window, or if the display is high DPI. * * You can disable logical coordinates by setting the mode to * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel - * resolution of the output window. + * resolution of the output window; it is safe to toggle logical presentation + * during the rendering of a frame: perhaps most of the rendering is done to + * specific dimensions but to make fonts look sharp, the app turns off logical + * presentation while drawing text. + * + * Letterboxing will only happen if logical presentation is enabled during + * SDL_RenderPresent; be sure to reenable it first if you were using it. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). @@ -1276,17 +1378,18 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \param w the width of the logical resolution. * \param h the height of the logical resolution. * \param mode the presentation mode used. - * \param scale_mode the scale mode used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertEventToRenderCoordinates * \sa SDL_GetRenderLogicalPresentation * \sa SDL_GetRenderLogicalPresentationRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); /** * Get device independent resolution and presentation mode for rendering. @@ -1297,16 +1400,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param w an int to be filled with the width. * \param h an int to be filled with the height. - * \param mode a pointer filled in with the presentation mode. - * \param scale_mode a pointer filled in with the scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); /** * Get the final presentation rectangle for rendering. @@ -1319,36 +1423,54 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param rect a pointer filled in with the final presentation rectangle, may * be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); /** * Get a point in render coordinates when given a point in window coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param window_x the x coordinate in window coordinates. * \param window_y the y coordinate in window coordinates. * \param x a pointer filled with the x coordinate in render coordinates. * \param y a pointer filled with the y coordinate in render coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); /** * Get a point in window coordinates when given a point in render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param x the x coordinate in render coordinates. * \param y the y coordinate in render coordinates. @@ -1356,65 +1478,95 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Rendere * coordinates. * \param window_y a pointer filled with the y coordinate in window * coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); /** * Convert the coordinates in an event to render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * Various event types are converted with this function: mouse, touch, pen, + * etc. + * * Touch coordinates are converted from normalized coordinates in the window * to non-normalized rendering coordinates. * - * Once converted, the coordinates may be outside the rendering area. + * Relative mouse coordinates (xrel and yrel event fields) are _also_ + * converted. Applications that do not want these fields converted should use + * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of + * converting the entire event structure. + * + * Once converted, coordinates may be outside the rendering area. * * \param renderer the rendering context. * \param event the event to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderCoordinatesFromWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); /** * Set the drawing area for rendering on the current target. * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL * to set the viewport to the entire target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_RenderViewportSet */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the drawing area for the current target. * * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current drawing area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderViewportSet * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); /** * Return whether an explicit rectangle was set as the viewport. @@ -1424,15 +1576,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *rendere * viewport is always reset when changing rendering targets. * * \param renderer the rendering context. - * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target). + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); /** * Get the safe area for rendering within the current viewport. @@ -1447,12 +1601,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect a pointer filled in with the area that is safe for interactive * content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); /** * Set the clip rectangle for rendering on the specified target. @@ -1460,15 +1616,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the clip area, relative to * the viewport, or NULL to disable clipping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_RenderClipEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the clip rectangle for the current target. @@ -1476,29 +1634,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current clipping area * or an empty rectangle if clipping is disabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderClipEnabled * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); /** * Get whether clipping is enabled on the given renderer. * * \param renderer the rendering context. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. + * \returns true if clipping is enabled or false if not; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); /** * Set the drawing scale for rendering on the current target. @@ -1514,14 +1676,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * \param renderer the rendering context. * \param scaleX the horizontal scaling factor. * \param scaleY the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); /** * Get the drawing scale for the current target. @@ -1529,14 +1693,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, * \param renderer the rendering context. * \param scaleX a pointer filled in with the horizontal scaling factor. * \param scaleY a pointer filled in with the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); /** * Set the color used for drawing operations. @@ -1551,15 +1717,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to * specify how the alpha channel is used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColor * \sa SDL_SetRenderDrawColorFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Set the color used for drawing operations (Rect, Line and Clear). @@ -1574,15 +1742,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *render * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is * used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1596,15 +1766,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *r * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1618,15 +1790,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *render * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColorFloat * \sa SDL_GetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); /** * Set the color scale used for render operations. @@ -1641,28 +1815,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *r * * \param renderer the rendering context. * \param scale the color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); /** * Get the color scale used for render operations. * * \param renderer the rendering context. * \param scale a pointer filled in with the current color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); /** * Set the blend mode used for drawing operations (Fill and Line). @@ -1671,28 +1849,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *rende * * \param renderer the rendering context. * \param blendMode the SDL_BlendMode to use for blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); /** * Get the blend mode used for drawing operations. * * \param renderer the rendering context. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); /** * Clear the current rendering target with the drawing color. @@ -1703,14 +1885,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *re * SDL_SetRenderDrawColor() when needed. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. @@ -1718,14 +1902,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \param renderer the renderer which should draw a point. * \param x the x coordinate of the point. * \param y the y coordinate of the point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); /** * Draw multiple points on the current rendering target at subpixel precision. @@ -1733,14 +1919,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, flo * \param renderer the renderer which should draw multiple points. * \param points the points to draw. * \param count the number of points to draw. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a line on the current rendering target at subpixel precision. @@ -1750,14 +1938,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, co * \param y1 the y coordinate of the start point. * \param x2 the x coordinate of the end point. * \param y2 the y coordinate of the end point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLines */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); /** * Draw a series of connected lines on the current rendering target at @@ -1766,14 +1956,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, floa * \param renderer the renderer which should draw multiple lines. * \param points the points along the lines. * \param count the number of points, drawing count-1 lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLine */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a rectangle on the current rendering target at subpixel precision. @@ -1781,14 +1973,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, con * \param renderer the renderer which should draw a rectangle. * \param rect a pointer to the destination rectangle, or NULL to outline the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Draw some number of rectangles on the current rendering target at subpixel @@ -1797,14 +1991,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, cons * \param renderer the renderer which should draw multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Fill a rectangle on the current rendering target with the drawing color at @@ -1813,14 +2009,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, con * \param renderer the renderer which should fill a rectangle. * \param rect a pointer to the destination rectangle, or NULL for the entire * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Fill some number of rectangles on the current rendering target with the @@ -1829,14 +2027,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, * \param renderer the renderer which should fill multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Copy a portion of the texture to the current rendering target at subpixel @@ -1848,15 +2048,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, * texture. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTextureRotated * \sa SDL_RenderTextureTiled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); /** * Copy a portion of the source texture to the current rendering target, with @@ -1875,17 +2077,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, S * around dstrect.w/2, dstrect.h/2). * \param flip an SDL_FlipMode value stating which flipping actions should be * performed on the texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, - const double angle, const SDL_FPoint *center, - const SDL_FlipMode flip); + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); + +/** + * Copy a portion of the source texture to the current rendering target, with + * affine transform, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param origin a pointer to a point indicating where the top-left corner of + * srcrect should be mapped to, or NULL for the rendering + * target's origin. + * \param right a pointer to a point indicating where the top-right corner of + * srcrect should be mapped to, or NULL for the rendering + * target's top-right corner. + * \param down a pointer to a point indicating where the bottom-left corner of + * srcrect should be mapped to, or NULL for the rendering target's + * bottom-left corner. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FPoint *origin, + const SDL_FPoint *right, const SDL_FPoint *down); /** * Tile a portion of the texture to the current rendering target at subpixel @@ -1903,14 +2137,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *rend * 64x64 tiles. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); /** * Perform a scaled copy using the 9-grid algorithm to the current rendering @@ -1935,14 +2171,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *render * corner of `dstrect`, or 0.0f for an unscaled copy. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); /** * Render a list of triangles, optionally using a texture and indices into the @@ -1957,14 +2195,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *render * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices number of indices. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometryRaw */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices); @@ -1987,14 +2227,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * if NULL all vertices will be rendered in sequential order. * \param num_indices number of indices. * \param size_indices index size: 1 (byte), 2 (short), 4 (int). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometry */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, @@ -2017,7 +2259,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *rendere * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); @@ -2041,18 +2285,20 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * pixel. * * Please note, that in case of rendering to a texture - there is **no need** - * to call `SDL_RenderPresent` after drawing needed objects to a texture, you - * are only required to change back the rendering target to default via - * `SDL_SetRenderTarget(renderer, NULL)` afterwards, as textures by themselves - * do not have a concept of backbuffers. + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \threadsafety You may only call this function on the main thread. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_RenderClear @@ -2067,7 +2313,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \sa SDL_SetRenderDrawBlendMode * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); /** * Destroy the specified texture. @@ -2077,7 +2323,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureFromSurface @@ -2092,7 +2340,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer */ @@ -2122,12 +2372,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * be prepared to make changes if specific state needs to be protected. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); /** * Get the CAMetalLayer associated with the given Metal renderer. @@ -2139,7 +2391,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalCommandEncoder */ @@ -2160,7 +2414,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalLayer */ @@ -2187,15 +2443,15 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not * needed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is **NOT** safe to call this function from two threads at * once. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); /** * Toggle VSync of the given renderer. @@ -2204,21 +2460,23 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer * * The `vsync` parameter can be 1 to synchronize present with every vertical * refresh, 2 to synchronize present with every second vertical refresh, etc., - * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), - * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is - * supported by every driver, so you should check the return value to see - * whether the requested setting is supported. + * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or + * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by + * every driver, so you should check the return value to see whether the + * requested setting is supported. * * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); #define SDL_RENDERER_VSYNC_DISABLED 0 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1) @@ -2229,14 +2487,96 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, * \param renderer the renderer to toggle. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetRenderVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); + +/** + * The size, in pixels, of a single SDL_RenderDebugText() character. + * + * The font is monospaced and square, so this applies to all characters. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + */ +#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8 + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a string of text to an SDL_Renderer. Note that + * this is a convenience function for debugging, with severe limitations, and + * not intended to be used for production apps and games. + * + * Among these limitations: + * + * - It accepts UTF-8 strings, but will only renders ASCII characters. + * - It has a single, tiny size (8x8 pixels). One can use logical presentation + * or scaling to adjust it, but it will be blurry. + * - It uses a simple, hardcoded bitmap font. It does not allow different font + * selections and it does not support truetype, for proper scaling. + * - It does no word-wrapping and does not treat newline characters as a line + * break. If the text goes out of the window, it's gone. + * + * For serious text rendering, there are several good options, such as + * SDL_ttf, stb_truetype, or other external libraries. + * + * On first use, this will create an internal texture for rendering glyphs. + * This texture will live until the renderer is destroyed. + * + * The text is drawn in the color specified by SDL_SetRenderDrawColor(). + * + * \param renderer the renderer which should draw a line of text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param str the string to render. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugTextFormat + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str); + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a printf()-style format string to a renderer. + * Note that this is a convinence function for debugging, with severe + * limitations, and is not intended to be used for production apps and games. + * + * For the full list of limitations and other useful information, see + * SDL_RenderDebugText. + * + * \param renderer the renderer which should draw the text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param fmt the format string to draw. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h index f78e5d9..18f7c4d 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h @@ -1,22 +1,22 @@ /* - Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga - 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. + 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: + 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. + 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. */ /* WIKI CATEGORY: Version */ @@ -48,9 +48,9 @@ */ #define SDL_REVISION "Some arbitrary string decided at SDL build time" #elif defined(SDL_VENDOR_INFO) -#define SDL_REVISION SDL_VENDOR_INFO +#define SDL_REVISION "release-3.2.0-0-g535d80bad (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "" +#define SDL_REVISION "release-3.2.0-0-g535d80bad" #endif #endif /* SDL_revision_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h index ccf8bb5..9650a6c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryScancode * * Defines keyboard scancodes. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_scancode_h_ @@ -42,7 +47,7 @@ * The values in this enumeration are based on the USB usage page standard: * https://usb.org/sites/default/files/hut1_5.pdf * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_Scancode { @@ -417,8 +422,8 @@ typedef enum SDL_Scancode SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h index 3ae4856..b220f05 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategorySensor * * SDL sensor management. + * + * These APIs grant access to gyros and accelerometers on various platforms. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ @@ -41,14 +47,10 @@ extern "C" { #endif /** - * SDL_sensor.h + * The opaque structure used to identify an opened SDL sensor. * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system - * for sensors, and load appropriate drivers. + * \since This struct is available since SDL 3.2.0. */ - -struct SDL_Sensor; typedef struct SDL_Sensor SDL_Sensor; /** @@ -57,7 +59,7 @@ typedef struct SDL_Sensor SDL_Sensor; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SensorID; @@ -69,7 +71,7 @@ typedef Uint32 SDL_SensorID; * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the * earth, which is a positive Y value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_STANDARD_GRAVITY 9.80665f @@ -123,7 +125,7 @@ typedef Uint32 SDL_SensorID; * * The gyroscope axis data is not changed when the device is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayOrientation */ @@ -151,7 +153,7 @@ typedef enum SDL_SensorType * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); @@ -163,7 +165,7 @@ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); * \param instance_id the sensor instance ID. * \returns the sensor name, or NULL if `instance_id` is not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id); @@ -176,7 +178,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID ins * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is * not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID instance_id); @@ -189,7 +191,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID i * \returns the sensor platform dependent type, or -1 if `instance_id` is not * valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); @@ -200,7 +202,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id); @@ -211,7 +213,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); @@ -222,7 +224,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instan * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); @@ -233,7 +235,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor * \returns the sensor name or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); @@ -244,7 +246,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor); @@ -254,7 +256,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor) * \param sensor the SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor); @@ -265,7 +267,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor) * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); @@ -277,19 +279,19 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); * \param sensor the SDL_Sensor object to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** * Close a sensor previously opened with SDL_OpenSensor(). * * \param sensor the SDL_Sensor object to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); @@ -302,7 +304,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); * This needs to be called from the thread that initialized the sensor * subsystem. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateSensors(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h index 5539f2a..4e15a3c 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,25 @@ /** * # CategoryStdinc * - * This is a general header that includes C language support. It implements a - * subset of the C runtime: these should all behave the same way as their C - * runtime equivalents, but with an SDL_ prefix. + * SDL provides its own implementation of some of the most important C runtime + * functions. + * + * Using these functions allows an app to have access to common C + * functionality without depending on a specific C runtime (or a C runtime at + * all). More importantly, the SDL implementations work identically across + * platforms, so apps can avoid surprises like snprintf() behaving differently + * between Windows and Linux builds, or itoa() only existing on some + * platforms. + * + * For many of the most common functions, like SDL_memcpy, SDL might just call + * through to the usual C runtime behind the scenes, if it makes sense to do + * so (if it's faster and always available/reliable on a given platform), + * reducing library size and offering the most optimized option. + * + * SDL also offers other C-runtime-adjacent functionality in this header that + * either isn't, strictly speaking, part of any C runtime standards, like + * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better + * options, like SDL_strlcpy(), which functions as a safer form of strcpy(). */ #ifndef SDL_stdinc_h_ @@ -32,17 +48,34 @@ #include -#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -#include -#endif #include -#ifndef __cplusplus -#include -#endif #include #include #include +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H) +#if __has_include() +#define SDL_INCLUDE_STDBOOL_H +#endif +#endif +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + #ifndef SDL_DISABLE_ALLOCA # ifndef alloca # ifdef HAVE_ALLOCA_H @@ -74,31 +107,120 @@ void *alloca(size_t); # endif #endif -#ifdef SIZE_MAX + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Don't let SDL use "long long" C types. + * + * SDL will define this if it believes the compiler doesn't understand the + * "long long" syntax for C datatypes. This can happen on older compilers. + * + * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it + * is safe to define this yourself to build against the SDL headers. + * + * If this is defined, it will remove access to some C runtime support + * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype + * explicitly. The rest of SDL will still be available. + * + * SDL's own source code cannot be built with a compiler that has this + * defined, for various technical reasons. + */ +#define SDL_NOLONGLONG 1 + +#elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */ +# define SDL_NOLONGLONG 1 +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The largest value that a `size_t` can hold for the target platform. + * + * `size_t` is generally the same size as a pointer in modern times, but this + * can get weird on very old and very esoteric machines. For example, on a + * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment + * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with + * the offset into an individual segment. + * + * In modern times, it's generally expected to cover an entire linear address + * space. But be careful! + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SIZE_MAX SIZE_MAX + +#elif defined(SIZE_MAX) # define SDL_SIZE_MAX SIZE_MAX #else # define SDL_SIZE_MAX ((size_t) -1) #endif +#ifndef SDL_COMPILE_TIME_ASSERT +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + /** - * Check if the compiler supports a given builtin. - * Supported by virtually all clang versions and recent gcc. Use this - * instead of checking the clang version if possible. + * A compile-time assertion. + * + * This can check constant values _known to the compiler at build time_ for + * correctness, and end the compile with the error if they fail. + * + * Often times these are used to verify basic truths, like the size of a + * datatype is what is expected: + * + * ```c + * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); + * ``` + * + * The `name` parameter must be a valid C symbol, and must be unique across + * all compile-time asserts in the same compilation unit (one run of the + * compiler), or the build might fail with cryptic errors on some targets. + * This is used with a C language trick that works on older compilers that + * don't support better assertion techniques. + * + * If you need an assertion that operates at runtime, on variable data, you + * should try SDL_assert instead. + * + * \param name a unique identifier for this assertion. + * \param x the value to test. Must be a boolean value. + * + * \threadsafety This macro doesn't generate any code to run. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_assert */ -#ifdef __has_builtin -#define SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define SDL_HAS_BUILTIN(x) 0 +#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x) +#elif defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] #endif /** - * The number of elements in an array. + * The number of elements in a static array. + * + * This will compile but return incorrect results for a pointer to an array; + * it has to be an array the compiler knows the size of. * * This macro looks like it double-evaluates the argument, but it does so * inside of `sizeof`, so there are no side-effects here, as expressions do * not actually run any code in these cases. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) @@ -111,7 +233,9 @@ void *alloca(size_t); * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * ``` * - * \since This macro is available since SDL 3.0.0. + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -122,7 +246,76 @@ void *alloca(size_t); * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). */ /* @{ */ -#ifdef __cplusplus + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) #define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) #define SDL_static_cast(type, expression) static_cast(expression) #define SDL_const_cast(type, expression) const_cast(expression) @@ -131,9 +324,23 @@ void *alloca(size_t); #define SDL_static_cast(type, expression) ((type)(expression)) #define SDL_const_cast(type, expression) ((type)(expression)) #endif + /* @} *//* Cast operators */ -/* Define a four character code as a Uint32 */ +/** + * Define a four character code as a Uint32. + * + * \param A the first ASCII character. + * \param B the second ASCII character. + * \param C the third ASCII character. + * \param D the fourth ASCII character. + * \returns the four characters converted into a Uint32, one character + * per-byte. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FOURCC(A, B, C, D) \ ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ @@ -149,7 +356,7 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -162,63 +369,49 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ -#elif defined(INT64_C) +#else /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +#ifndef SDL_SINT64_C +#if defined(INT64_C) #define SDL_SINT64_C(c) INT64_C(c) -#define SDL_UINT64_C(c) UINT64_C(c) #elif defined(_MSC_VER) #define SDL_SINT64_C(c) c ## i64 -#define SDL_UINT64_C(c) c ## ui64 #elif defined(__LP64__) || defined(_LP64) #define SDL_SINT64_C(c) c ## L -#define SDL_UINT64_C(c) c ## UL #else #define SDL_SINT64_C(c) c ## LL +#endif +#endif /* !SDL_SINT64_C */ + +#ifndef SDL_UINT64_C +#if defined(UINT64_C) +#define SDL_UINT64_C(c) UINT64_C(c) +#elif defined(_MSC_VER) +#define SDL_UINT64_C(c) c ## ui64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_UINT64_C(c) c ## UL +#else #define SDL_UINT64_C(c) c ## ULL #endif +#endif /* !SDL_UINT64_C */ + +#endif /* !SDL_WIKI_DOCUMENTATION_SECTION */ /** * \name Basic data types */ /* @{ */ -/** - * A boolean false. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_FALSE false - -/** - * A boolean true. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_TRUE true - -/** - * A boolean type: true or false. - * - * \since This datatype is available since SDL 3.0.0. - * - * \sa SDL_TRUE - * \sa SDL_FALSE - */ -typedef bool SDL_bool; - /** * A signed 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ @@ -227,7 +420,7 @@ typedef int8_t Sint8; /** * An unsigned 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ @@ -236,7 +429,7 @@ typedef uint8_t Uint8; /** * A signed 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ @@ -245,7 +438,7 @@ typedef int16_t Sint16; /** * An unsigned 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ @@ -254,7 +447,7 @@ typedef uint16_t Uint16; /** * A signed 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ @@ -263,7 +456,7 @@ typedef int32_t Sint32; /** * An unsigned 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ @@ -272,7 +465,7 @@ typedef uint32_t Uint32; /** * A signed 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ @@ -283,7 +476,7 @@ typedef int64_t Sint64; /** * An unsigned 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -299,7 +492,7 @@ typedef uint64_t Uint64; * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with * SDL_TimeToWindows() and SDL_TimeFromWindows(). * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_MAX_SINT64 * \sa SDL_MIN_SINT64 @@ -325,40 +518,217 @@ typedef Sint64 SDL_Time; * Equals by default to platform-defined `FLT_EPSILON`, or * `1.1920928955078125e-07F` if that's not available. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ #endif /* @} *//* Floating-point constants */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A printf-formatting string for an Sint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs64 "lld" + +/** + * A printf-formatting string for a Uint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu64 "llu" + +/** + * A printf-formatting string for a Uint64 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx64 "llx" + +/** + * A printf-formatting string for a Uint64 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX64 "llX" + +/** + * A printf-formatting string for an Sint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs32 "d" + +/** + * A printf-formatting string for a Uint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu32 "u" + +/** + * A printf-formatting string for a Uint32 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx32 "x" + +/** + * A printf-formatting string for a Uint32 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX32 "X" + +/** + * A printf-formatting string prefix for a `long long` value. + * + * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu, + * SDL_PRILLx, or SDL_PRILLX instead. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILL_PREFIX "ll" + +/** + * A printf-formatting string for a `long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLd SDL_PRILL_PREFIX "d" + +/** + * A printf-formatting string for a `unsigned long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLu SDL_PRILL_PREFIX "u" + +/** + * A printf-formatting string for an `unsigned long long` value as lower-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLx SDL_PRILL_PREFIX "x" + +/** + * A printf-formatting string for an `unsigned long long` value as upper-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* SDL_WIKI_DOCUMENTATION_SECTION */ + /* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. + * should define these but this is not true all platforms. * (for example win32) */ #ifndef SDL_PRIs64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIs64 "I64d" -#elif defined(PRIs64) -#define SDL_PRIs64 PRIs64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(PRId64) +#define SDL_PRIs64 PRId64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIs64 "ld" #else #define SDL_PRIs64 "lld" #endif #endif #ifndef SDL_PRIu64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIu64 "I64u" #elif defined(PRIu64) #define SDL_PRIu64 PRIu64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIu64 "lu" #else #define SDL_PRIu64 "llu" #endif #endif #ifndef SDL_PRIx64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIx64 "I64x" #elif defined(PRIx64) #define SDL_PRIx64 PRIx64 @@ -369,7 +739,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIX64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIX64 "I64X" #elif defined(PRIX64) #define SDL_PRIX64 PRIX64 @@ -407,9 +777,318 @@ typedef Sint64 SDL_Time; #define SDL_PRIX32 "X" #endif #endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#endif +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Macro that annotates function params with input buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + * ``` + * + * This notes that `src` should be `len` bytes in size and is only read by the + * function. The compiler or other analysis tools can warn when this doesn't + * appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) + +/** + * Macro that annotates function params with input/output string buffer size. + * + * If we were to annotate `strlcat`: + * + * ```c + * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + * ``` + * + * This notes that `dst` is a null-terminated C string, should be `maxlen` + * bytes in size, and is both read from and written to by the function. The + * compiler or other analysis tools can warn when this doesn't appear to be + * the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) + +/** + * Macro that annotates function params with output string buffer size. + * + * If we were to annotate `snprintf`: + * + * ```c + * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...); + * ``` + * + * This notes that `text` is a null-terminated C string, should be `maxlen` + * bytes in size, and is only written to by the function. The compiler or + * other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `wcsncpy`: + * + * ```c + * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` wchar_t in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for + * bytes. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_CAP(x) _Out_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) + +/** + * Macro that annotates function params with output buffer string size. + * + * If we were to annotate `strcpy`: + * + * ```c + * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and a zero-terminated string is written to it by the function. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +/** + * Macro that annotates function params as printf-style format strings. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a printf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ + +/** + * Macro that annotates function params as scanf-style format strings. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a scanf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ + +/** + * Macro that annotates a vararg function that operates like printf. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like printf. + * + * If we were to annotate `vfprintf`: + * + * ```c + * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like scanf. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by `...`. The compiler or other analysis tools can warn when this + * doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like scanf. + * + * If we were to annotate `vfscanf`: + * + * ```c + * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by a va_list. The compiler or other analysis tools can warn when + * this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like wprintf. + * + * If we were to annotate `fwprintf`: + * + * ```c + * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ + +/** + * Macro that annotates a va_list function that operates like wprintf. + * + * If we were to annotate `vfwprintf`: + * + * ```c + * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + +#elif defined(SDL_DISABLE_ANALYZE_MACROS) #define SDL_IN_BYTECAP(x) #define SDL_INOUT_Z_CAP(x) #define SDL_OUT_Z_CAP(x) @@ -423,7 +1102,7 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -447,53 +1126,45 @@ typedef Sint64 SDL_Time; #define SDL_PRINTF_FORMAT_STRING #define SDL_SCANF_FORMAT_STRING #endif -#ifdef __GNUC__ +#if defined(__GNUC__) || defined(__clang__) #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(bool, sizeof(SDL_bool) == 1); -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +#endif +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ /** \endcond */ @@ -523,7 +1194,96 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); extern "C" { #endif -#ifndef SDL_DISABLE_ALLOCA +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Allocate memory on the stack (maybe). + * + * If SDL knows how to access alloca() on the current platform, it will use it + * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to + * heap-allocate memory. + * + * Since this might not be stack memory at all, it's important that you check + * the returned pointer for NULL, and that you call SDL_stack_free on the + * memory when done with it. Since this might be stack memory, it's important + * that you don't allocate large amounts of it, or allocate in a loop without + * returning from the function, so the stack doesn't overflow. + * + * \param type the datatype of the memory to allocate. + * \param count the number of `type` objects to allocate. + * \returns newly-allocated memory, or NULL on failure. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_free + */ +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ +#define SDL_stack_free(data) +#elif !defined(SDL_DISABLE_ALLOCA) #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) #define SDL_stack_free(data) #else @@ -531,14 +1291,184 @@ extern "C" { #define SDL_stack_free(data) SDL_free(data) #endif +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If you want to allocate memory aligned to a specific alignment, consider + * using SDL_aligned_alloc(). + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void (SDLCALL *SDL_free_func)(void *mem); /** @@ -556,7 +1486,7 @@ typedef void (SDLCALL *SDL_free_func)(void *mem); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, @@ -575,7 +1505,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func * unlikely event of a background thread calling * SDL_SetMemoryFunctions simultaneously. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions @@ -599,42 +1529,42 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \param calloc_func custom calloc function. * \param realloc_func custom realloc function. * \param free_func custom free function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but one * should not replace the memory functions once any allocations * are made! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_calloc_func calloc_func, SDL_realloc_func realloc_func, SDL_free_func free_func); /** - * Allocate memory aligned to a specific value. - * - * If `alignment` is less than the size of `void *`, then it will be increased - * to match that. - * - * The returned memory address will be a multiple of the alignment value, and - * the amount of memory allocated will be a multiple of the alignment value. + * Allocate memory aligned to a specific alignment. * * The memory returned by this function must be freed with SDL_aligned_free(), - * and _not_ SDL_free. + * _not_ SDL_free(). * - * \param alignment the alignment requested. + * If `alignment` is less than the size of `void *`, it will be increased to + * match that. + * + * The returned memory address will be a multiple of the alignment value, and + * the size of the memory allocated will be a multiple of the alignment value. + * + * \param alignment the alignment of the memory. * \param size the size to allocate. - * \returns a pointer to the aligned memory. + * \returns a pointer to the aligned memory, or NULL if allocation failed. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_free */ @@ -646,11 +1576,13 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment * The pointer is no longer valid after this call and cannot be dereferenced * anymore. * - * \param mem a pointer previously returned by SDL_aligned_alloc. + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc */ @@ -659,31 +1591,552 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); /** * Get the number of outstanding (unfreed) allocations. * - * \returns the number of allocations. + * \returns the number of allocations or -1 if allocation counting is + * disabled. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); -extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); -extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); +/** + * Compute the absolute value of `x`. + * + * \param x an integer value. + * \returns the absolute value of x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); -/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ +/** + * Return the lesser of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) + +/** + * Return the greater of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `>` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) + +/** + * Return a value clamped to a range. + * + * If `x` is outside the range a values between `a` and `b`, the returned + * value will be `a` or `b` as appropriate. Otherwise, `x` is returned. + * + * This macro will produce incorrect results if `b` is less than `a`. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` and `>` operators. However, it double-evaluates all its parameters, so + * do not use expressions with side-effects here. + * + * \param x the value to compare. + * \param a the low end value. + * \param b the high end value. + * \returns x, clamped between a and b. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) /** @@ -697,7 +2150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); @@ -712,7 +2165,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); @@ -727,7 +2180,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); @@ -742,7 +2195,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); @@ -757,7 +2210,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); @@ -772,7 +2225,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); @@ -787,7 +2240,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isgraph * \sa SDL_isalnum @@ -812,7 +2265,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); @@ -827,7 +2280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); @@ -842,7 +2295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); @@ -861,7 +2314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); @@ -880,7 +2333,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isprint */ @@ -900,7 +2353,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); @@ -918,13 +2371,96 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); +/** + * Calculate a CRC-16 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-16 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-16 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); + +/** + * Calculate a CRC-32 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-32 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-32 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); +/** + * Calculate a 32-bit MurmurHash3 value for a block of data. + * + * https://en.wikipedia.org/wiki/MurmurHash + * + * A seed may be specified, which changes the final results consistently, but + * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous + * result from this function back into itself as the next seed value to + * calculate a hash in chunks; it won't produce the same hash as it would if + * the same data was provided in a single call. + * + * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not + * cryptographically secure, so it shouldn't be used for hashing top-secret + * data. + * + * \param data the data to be hashed. + * \param len the size of data, in bytes. + * \param seed a value that alters the final hash value. + * \returns a Murmur3 32-bit hash value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); + +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memmove + */ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memcpy */ @@ -935,10 +2471,52 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD #define SDL_memcpy memcpy #endif + +/** + * A macro to copy memory between objects, with basic type checking. + * + * SDL_memcpy and SDL_memmove do not care where you copy memory to and from, + * which can lead to bugs. This macro aims to avoid most of those bugs by + * making sure that the source and destination are both pointers to objects + * that are the same size. It does not check that the objects are the same + * _type_, just that the copy will not overflow either object. + * + * The size check happens at compile time, and the compiler will throw an + * error if the objects are different sizes. + * + * Generally this is intended to copy a single object, not an array. + * + * This macro looks like it double-evaluates its parameters, but the extras + * them are in `sizeof` sections, which generate no code nor side-effects. + * + * \param dst a pointer to the destination object. Must not be NULL. + * \param src a pointer to the source object. Must not be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ #define SDL_copyp(dst, src) \ { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) +/** + * Copy memory ranges that might overlap. + * + * It is okay for the memory regions to overlap. If you are confident that the + * regions never overlap, using SDL_memcpy() may improve performance. + * + * \param dst The destination memory region. Must not be NULL. + * \param src The source memory region. Must not be NULL. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memcpy + */ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memmove */ @@ -949,7 +2527,44 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, S #define SDL_memmove memmove #endif +/** + * Initialize all bytes of buffer of memory to a specific value. + * + * This function will set `len` bytes, pointed to by `dst`, to the value + * specified in `c`. + * + * Despite `c` being an `int` instead of a `char`, this only operates on + * bytes; `c` must be a value between 0 and 255, inclusive. + * + * \param dst the destination memory region. Must not be NULL. + * \param c the byte value to set. + * \param len the length, in bytes, to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); + +/** + * Initialize all 32-bit words of buffer of memory to a specific value. + * + * This function will set a buffer of `dwords` Uint32 values, pointed to by + * `dst`, to the value specified in `val`. + * + * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited + * to a range of 0-255. + * + * \param dst the destination memory region. Must not be NULL. + * \param val the Uint32 value to set. + * \param dwords the number of Uint32 values to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); /* Take advantage of compiler optimizations for memset */ @@ -960,18 +2575,255 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo #define SDL_memset memset #endif +/** + * Clear an object's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an object, not a pointer to an object, nor an array. + * + * \param x the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zerop + * \sa SDL_zeroa + */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) + +/** + * Clear an object's memory to zero, using a pointer. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires a pointer to an object, not an object itself, nor an array. + * + * \param x a pointer to the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) + +/** + * Clear an array's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the array size, so + * there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an array, not an object, nor a pointer to an object. + * + * \param x an array to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) + +/** + * Compare two buffers of memory. + * + * \param s1 the first buffer to compare. NULL is not permitted! + * \param s2 the second buffer to compare. NULL is not permitted! + * \param len the number of bytes to compare between the buffers. + * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is + * "greater than" s2, and zero if the buffers match exactly for `len` + * bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); +/** + * This works exactly like wcslen() but doesn't require access to a C runtime. + * + * Counts the number of wchar_t values in `wstr`, excluding the null + * terminator. + * + * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \returns the length (in wchar_t values, excluding the null terminator) of + * `wstr`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcsnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); + +/** + * This works exactly like wcsnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the + * null terminator. + * + * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * Also, `maxlen` is a count of wide characters, not bytes! + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \param maxlen The maximum amount of wide characters to count. + * \returns the length (in wide characters, excluding the null terminator) of + * `wstr` but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * Copy a wide string. + * + * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then + * appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` is 0, no wide characters are copied and no null terminator is + * written. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated wide string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcat + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \param src The second null-terminated wide string. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Allocate a copy of a wide string. + * + * This allocates enough space for a null-terminated copy of `wstr`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param wstr the string to copy. + * \returns a pointer to the newly-allocated wide string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); + +/** + * Search a wide string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); + +/** + * Search a wide string, up to n wide chars, for the first instance of a + * specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * value to end the string, or `maxlen` wide character have been examined. It + * is possible to use this function on a wide string without a null + * terminator. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \param maxlen the maximum number of wide characters to search in + * `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -989,7 +2841,7 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); @@ -1020,7 +2872,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); @@ -1050,7 +2902,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t * * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); @@ -1092,19 +2944,228 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); +/** + * This works exactly like strlen() but doesn't require access to a C runtime. + * + * Counts the bytes in `str`, excluding the null terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the length (in bytes, excluding the null terminator) of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); + +/** + * This works exactly like strnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null + * terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \param maxlen The maximum amount of bytes to count. + * \returns the length (in bytes, excluding the null terminator) of `src` but + * never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * Copy a string. + * + * This function copies up to `maxlen` - 1 characters from `src` to `dst`, + * then appends a null terminator. + * + * If `maxlen` is 0, no characters are copied and no null terminator is + * written. + * + * If you want to copy an UTF-8 string but need to ensure that multi-byte + * sequences are not truncated, consider using SDL_utf8strlcpy(). + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated string to copy. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param dst_bytes The length (in bytes) of the destination buffer. Must not + * be 0. + * \returns the number of bytes written, excluding the null terminator. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \param src The second null-terminated string. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of the + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Allocate a copy of a string. + * + * This allocates enough space for a null-terminated copy of `str`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); + +/** + * Allocate a copy of a string, up to n characters. + * + * This allocates enough space for a null-terminated copy of `str`, up to + * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into + * this space. + * + * If the string is longer than `maxlen` bytes, the returned string will be + * `maxlen` bytes long, plus a null-terminator character that isn't included + * in the count. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \param maxlen the maximum length of the copied string, not counting the + * null-terminator character. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); + +/** + * Reverse a string's contents. + * + * This reverses a null-terminated string in-place. Only the content of the + * string is reversed; the null-terminator character remains at the end of the + * reversed string. + * + * **WARNING**: This function reverses the _bytes_ of the string, not the + * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this + * will ruin the string data. You should only use this function on strings + * that are completely comprised of low ASCII characters. + * + * \param str the string to reverse. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -1122,7 +3183,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strlwr */ @@ -1143,34 +3204,592 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strupr */ extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); +/** + * Search a string for the first instance of a specific byte. + * + * The search ends once it finds the requested byte value, or a null + * terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the first instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); + +/** + * Search a string for the last instance of a specific byte. + * + * The search must go until it finds a null terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the last instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); + +/** + * Search a string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); + +/** + * Search a string, up to n bytes, for the first instance of a specific + * substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string, or `maxlen` bytes have been examined. It is + * possible to use this function on a string without a null terminator. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \param maxlen the maximum number of bytes to search in `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); + +/** + * Search a UTF-8 string for the first instance of a specific substring, + * case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); -extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr); + +/** + * This works exactly like strtok_r() but doesn't require access to a C + * runtime. + * + * Break a string up into a series of tokens. + * + * To start tokenizing a new string, `str` should be the non-NULL address of + * the string to start tokenizing. Future calls to get the next token from the + * same string should specify a NULL. + * + * Note that this function will overwrite pieces of `str` with null chars to + * split it into tokens. This function cannot be used with const/read-only + * strings! + * + * `saveptr` just needs to point to a `char *` that can be overwritten; SDL + * will use this to save tokenizing state between calls. It is initialized if + * `str` is non-NULL, and used to resume tokenizing when `str` is NULL. + * + * \param str the string to tokenize, or NULL to continue tokenizing. + * \param delim the delimiter string that separates tokens. + * \param saveptr pointer to a char *, used for ongoing state. + * \returns A pointer to the next token, or NULL if no tokens remain. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr); + +/** + * Count the number of codepoints in a UTF-8 string. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strlen(). + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \returns The length (in codepoints, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strnlen + * \sa SDL_strlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); + +/** + * Count the number of codepoints in a UTF-8 string, up to n bytes. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strnlen(). + * + * The counting stops at `bytes` bytes (not codepoints!). This seems + * counterintuitive, but makes it easy to express the total size of the + * string's buffer. + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \param bytes The maximum amount of bytes to count. + * \returns The length (in codepoints, excluding the null terminator) of `src` + * but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strlen + * \sa SDL_strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); +/** + * Convert an integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +/** + * Convert an unsigned integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_itoa + * \sa SDL_ultoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); + +/** + * Convert a long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ultoa + * \sa SDL_itoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); + +/** + * Convert an unsigned long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +#ifndef SDL_NOLONGLONG + +/** + * Convert a long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ulltoa + * \sa SDL_itoa + * \sa SDL_ltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); + +/** + * Convert an unsigned long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); +#endif + +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to + * `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +#ifndef SDL_NOLONGLONG + +/** + * Parse a `long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long long`, the result is + * clamped to the minimum and maximum representable `long long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long long`, or 0 if no number could be + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); +#endif + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. The handling of + * scientific and hexadecimal notation is unspecified. + * - Whether or not INF and NAN can be parsed is unspecified. + * - The precision of the result is unspecified. + * + * \param str the null-terminated string to read. Must not be NULL. + * \param endp if not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \returns the parsed `double`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /** @@ -1189,7 +3808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); @@ -1219,7 +3838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); @@ -1247,7 +3866,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); @@ -1287,20 +3906,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + /** * The Unicode REPLACEMENT CHARACTER codepoint. * - * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string - * with encoding errors. + * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they + * encounter a UTF-8 string with encoding errors. * * This tends to render as something like a question mark in most places. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * + * \sa SDL_StepBackUTF8 * \sa SDL_StepUTF8 */ #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD @@ -1346,10 +3984,41 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); +/** + * Decode a UTF-8 string in reverse, one Unicode codepoint at a time. + * + * This will go to the start of the previous Unicode codepoint in the string, + * move `*pstr` to that location and return that codepoint. + * + * If `*pstr` is already at the start of the string), it will not advance + * `*pstr` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameter each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT. + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param start a pointer to the beginning of the UTF-8 string. + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \returns the previous Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr); + /** * Convert a single Unicode codepoint to UTF-8. * @@ -1375,18 +4044,200 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); - +/** + * This works exactly like sscanf() but doesn't require access to a C runtime. + * + * Scan a string, matching a format string, converting each '%' item and + * storing it to pointers provided through variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); + +/** + * This works exactly like vsscanf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_sscanf(), except it takes a `va_list` instead + * of using `...` variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` of pointers to values to be filled in with scanned + * items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like snprintf() but doesn't require access to a C + * runtime. + * + * Format a string of up to `maxlen`-1 bytes, converting each '%' item with + * values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * bytes will be written at all. + * + * This function returns the number of _bytes_ (not _characters_) that should + * be written, excluding the null-terminator character. If this returns a + * number >= `maxlen`, it means the output string was truncated. A negative + * return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * This works exactly like swprintf() but doesn't require access to a C + * runtime. + * + * Format a wide string of up to `maxlen`-1 wchar_t values, converting each + * '%' item with values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide + * characters will be written at all. + * + * This function returns the number of _wide characters_ (not _codepoints_) + * that should be written, excluding the null-terminator character. If this + * returns a number >= `maxlen`, it means the output string was truncated. A + * negative return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the wide string into. Must not be NULL. + * \param maxlen the maximum wchar_t values to write, including the + * null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like vsnprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); + +/** + * This works exactly like vswprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_swprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum wide characters to write, including the + * null-terminator. + * \param fmt a printf-style format wide string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like asprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it allocates a buffer large + * enough to hold the output string on behalf of the caller. + * + * On success, this function returns the number of bytes (not characters) + * comprising the output string, not counting the null-terminator character, + * and sets `*strp` to the newly-allocated string. + * + * On error, this function returns a negative number, and the value of `*strp` + * is undefined. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * This works exactly like vasprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_asprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** @@ -1401,7 +4252,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR * \threadsafety This should be called on the same thread that calls * SDL_rand*() * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits @@ -1436,7 +4287,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_randf @@ -1459,7 +4310,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_rand @@ -1481,7 +4332,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf(void); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_randf @@ -1516,7 +4367,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits_r @@ -1543,7 +4394,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_bits_r * \sa SDL_rand_r @@ -1569,18 +4420,34 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_r * \sa SDL_randf_r */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); - #ifndef SDL_PI_D + +/** + * The value of Pi, as a double-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_F + */ #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ #endif + #ifndef SDL_PI_F + +/** + * The value of Pi, as a single-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_D + */ #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ #endif @@ -1606,7 +4473,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acosf * \sa SDL_asin @@ -1636,7 +4503,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acos * \sa SDL_asinf @@ -1666,7 +4533,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asinf * \sa SDL_acos @@ -1696,7 +4563,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asin * \sa SDL_acosf @@ -1728,7 +4595,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atanf * \sa SDL_atan2 @@ -1760,7 +4627,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan * \sa SDL_atan2f @@ -1796,7 +4663,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1832,7 +4699,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1858,7 +4725,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceilf * \sa SDL_floor @@ -1886,7 +4753,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceil * \sa SDL_floorf @@ -1915,7 +4782,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabs @@ -1941,7 +4808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabsf @@ -1968,7 +4835,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cosf * \sa SDL_acos @@ -1996,7 +4863,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cos * \sa SDL_acosf @@ -2029,7 +4896,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_expf * \sa SDL_log @@ -2061,7 +4928,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_exp * \sa SDL_logf @@ -2083,7 +4950,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabsf */ @@ -2104,7 +4971,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabs */ @@ -2128,7 +4995,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floorf * \sa SDL_ceil @@ -2156,7 +5023,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floor * \sa SDL_ceilf @@ -2184,7 +5051,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_truncf * \sa SDL_fmod @@ -2213,7 +5080,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_trunc * \sa SDL_fmodf @@ -2242,7 +5109,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmodf * \sa SDL_modf @@ -2272,7 +5139,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmod * \sa SDL_truncf @@ -2292,7 +5159,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinff */ @@ -2306,7 +5173,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinf */ @@ -2320,7 +5187,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnanf */ @@ -2334,7 +5201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnan */ @@ -2362,7 +5229,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_logf * \sa SDL_log10 @@ -2392,7 +5259,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log * \sa SDL_expf @@ -2421,7 +5288,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10f * \sa SDL_log @@ -2451,7 +5318,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10 * \sa SDL_logf @@ -2471,7 +5338,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modff * \sa SDL_trunc @@ -2491,7 +5358,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modf * \sa SDL_truncf @@ -2523,7 +5390,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_powf * \sa SDL_exp @@ -2555,7 +5422,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_pow * \sa SDL_expf @@ -2582,7 +5449,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_roundf * \sa SDL_lround @@ -2611,7 +5478,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_round * \sa SDL_lroundf @@ -2640,7 +5507,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lroundf * \sa SDL_round @@ -2669,7 +5536,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lround * \sa SDL_roundf @@ -2697,7 +5564,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbnf * \sa SDL_pow @@ -2722,7 +5589,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbn * \sa SDL_powf @@ -2749,7 +5616,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sinf * \sa SDL_asin @@ -2765,7 +5632,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * Range: `-1 <= y <= 1` * * This function operates on single-precision floating point values, use - * SDL_sinf for double-precision floats. + * SDL_sin for double-precision floats. * * This function may use a different approximation across different versions, * platforms and configurations. i.e, it can return a different value given @@ -2777,7 +5644,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sin * \sa SDL_asinf @@ -2805,7 +5672,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrtf */ @@ -2831,7 +5698,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrt */ @@ -2857,7 +5724,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tanf * \sa SDL_sin @@ -2887,7 +5754,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tan * \sa SDL_sinf @@ -2897,12 +5764,13 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); */ extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); -/* The SDL implementation of iconv() returns these error codes */ -#define SDL_ICONV_ERROR (size_t)-1 -#define SDL_ICONV_E2BIG (size_t)-2 -#define SDL_ICONV_EILSEQ (size_t)-3 -#define SDL_ICONV_EINVAL (size_t)-4 - +/** + * An opaque handle representing string encoding conversion state. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + */ typedef struct SDL_iconv_data_t *SDL_iconv_t; /** @@ -2914,7 +5782,7 @@ typedef struct SDL_iconv_data_t *SDL_iconv_t; * \returns a handle that must be freed with SDL_iconv_close, or * SDL_ICONV_ERROR on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_close @@ -2929,7 +5797,7 @@ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, * \param cd The character set conversion handle. * \returns 0 on success, or -1 on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_open @@ -2941,7 +5809,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * This function converts text between encodings, reading from and writing to * a buffer. * - * It returns the number of succesful conversions. + * It returns the number of succesful conversions on success. On error, + * SDL_ICONV_E2BIG is returned when the output buffer is too small, or + * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, + * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte sequence. On + * error, this is the location of the problematic input sequence. On + * success, this is the end of the input sequence. + * - inbytesleft will be set to the number of bytes left to convert, which + * will be 0 on success. + * - outbuf will point to the location where to store the next output byte. + * - outbytesleft will be set to the number of bytes left in the output + * buffer. * * \param cd The character set conversion context, created in * SDL_iconv_open(). @@ -2950,23 +5833,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * \param inbytesleft The number of bytes in the input buffer. * \param outbuf Address of variable that points to the output buffer. * \param outbytesleft The number of bytes in the output buffer. - * \returns the number of conversions on success, else SDL_ICONV_E2BIG is - * returned when the output buffer is too small, or SDL_ICONV_EILSEQ - * is returned when an invalid input sequence is encountered, or - * SDL_ICONV_EINVAL is returned when an incomplete input sequence is - * encountered. + * \returns the number of conversions on success, or a negative error code. * - * On exit: - * - * - inbuf will point to the beginning of the next multibyte - * sequence. On error, this is the location of the problematic - * input sequence. On success, this is the end of the input - * sequence. - inbytesleft will be set to the number of bytes left - * to convert, which will be 0 on success. - outbuf will point to - * the location where to store the next output byte. - outbytesleft - * will be set to the number of bytes left in the output buffer. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -2976,6 +5845,12 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); +#define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */ +#define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */ +#define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */ +#define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */ + + /** * Helper function to convert a string's encoding in one call. * @@ -2995,7 +5870,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, * \param inbytesleft the size of the input string _in bytes_. * \returns a new string, converted to the new encoding, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -3006,12 +5881,65 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *inbuf, size_t inbytesleft); -/* Some helper macros for common cases... */ +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) + /* force builds using Clang's static analysis tools to use literal C runtime here, since there are possibly tests that are ineffective otherwise. */ #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) @@ -3034,6 +5962,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include @@ -3073,6 +6004,7 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #define SDL_wcsncmp wcsncmp #define SDL_strcasecmp strcasecmp #define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk #define SDL_sscanf sscanf #define SDL_vsscanf vsscanf #define SDL_snprintf snprintf @@ -3082,29 +6014,27 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); /** * Multiply two integers, checking for overflow. * - * If `a * b` would overflow, return -1. + * If `a * b` would overflow, return false. * - * Otherwise store `a * b` via ret and return 0. + * Otherwise store `a * b` via ret and return true. * * \param a the multiplicand. * \param b the multiplier. - * \param ret on non-overflow output, stores the multiplication result. May + * \param ret on non-overflow output, stores the multiplication result, may * not be NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is multiplied without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) { if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; + return false; } *ret = a * b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION @@ -3112,60 +6042,72 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, /* This needs to be wrapped in an inline rather than being a direct #define, * because __builtin_mul_overflow() is type-generic, but we want to be * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_mul_overflow(a, b, ret) == 0); } -#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) #endif #endif /** * Add two integers, checking for overflow. * - * If `a + b` would overflow, return -1. + * If `a + b` would overflow, return false. * - * Otherwise store `a + b` via ret and return 0. + * Otherwise store `a + b` via ret and return true. * * \param a the first addend. * \param b the second addend. - * \param ret on non-overflow output, stores the addition result. May not be + * \param ret on non-overflow output, stores the addition result, may not be * NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is added without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) { if (b > SDL_SIZE_MAX - a) { - return -1; + return false; } *ret = a + b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION #if SDL_HAS_BUILTIN(__builtin_add_overflow) /* This needs to be wrapped in an inline rather than being a direct #define, * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_add_overflow(a, b, ret) == 0); } -#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) #endif #endif /* This is a generic function pointer which should be cast to the type you expect */ -#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) typedef void *SDL_FunctionPointer; #else typedef void (*SDL_FunctionPointer)(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h index 91a90bc..8b89ace 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,222 @@ /** * # CategoryStorage * - * SDL storage container management. + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) { + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(data); + * } + * } + * } + * + * void ReadSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * + * void WriteSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(NULL, 0); + * if (title == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(title)) { + * SDL_Delay(1); + * } + * + * for (size_t i = 0; i < numFiles; i += 1) { + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) { + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * } + * + * SDL_CloseStorage(title); + * } + * + * void ReadSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) { + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * + * void WriteSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. */ #ifndef SDL_storage_h_ @@ -40,8 +255,6 @@ extern "C" { #endif -/* !!! FIXME: Don't let this ship without async R/W support!!! */ - /** * Function interface for SDL_Storage. * @@ -52,44 +265,61 @@ extern "C" { * It is not usually necessary to do this; SDL provides standard * implementations for many things you might expect to do with an SDL_Storage. * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_StorageInterface { + /* The version of this interface */ + Uint32 version; + /* Called when the storage is closed */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); /* Optional, returns whether the storage is currently ready for access */ - SDL_bool (SDLCALL *ready)(void *userdata); + bool (SDLCALL *ready)(void *userdata); /* Enumerate a directory, optional for write-only storage */ - SDL_bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); /* Get path information, optional for write-only storage */ - SDL_bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); /* Read a file from storage, optional for write-only storage */ - SDL_bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); /* Write a file to storage, optional for read-only storage */ - SDL_bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); /* Create a directory, optional for read-only storage */ - SDL_bool (SDLCALL *mkdir)(void *userdata, const char *path); + bool (SDLCALL *mkdir)(void *userdata, const char *path); /* Remove a file or empty directory, optional for read-only storage */ - SDL_bool (SDLCALL *remove)(void *userdata, const char *path); + bool (SDLCALL *remove)(void *userdata, const char *path); /* Rename a path, optional for read-only storage */ - SDL_bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); /* Copy a file, optional for read-only storage */ - SDL_bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); } SDL_StorageInterface; +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + /** * An abstract interface for filesystem access. * @@ -97,7 +327,7 @@ typedef struct SDL_StorageInterface * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create * an object with a custom implementation using SDL_OpenStorage. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Storage SDL_Storage; @@ -109,7 +339,7 @@ typedef struct SDL_Storage SDL_Storage; * \returns a title storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -132,7 +362,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *overr * \returns a user storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -156,7 +386,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, c * \returns a filesystem storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -176,16 +406,21 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * or SDL_OpenUserStorage(). * - * \param iface the function table to be used by this container. - * \param userdata the pointer that will be passed to the store interface. + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE * \sa SDL_ReadStorageFile * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -196,33 +431,33 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * Closes and frees a storage container. * * \param storage a storage container to close. - * \returns SDL_TRUE if the container was freed with no errors, SDL_FALSE - * otherwise; call SDL_GetError() for more information. Even if the - * function returns an error, the container data will be freed; the - * error is only for informational purposes. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenFileStorage * \sa SDL_OpenStorage * \sa SDL_OpenTitleStorage * \sa SDL_OpenUserStorage */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); /** * Checks if the storage container is ready to use. * - * This function should be called in regular intervals until it returns - * SDL_TRUE - however, it is not recommended to spinwait on this call, as the - * backend may depend on a synchronous message loop. + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. * * \param storage a storage container to query. - * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise. + * \returns true if the container is ready, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); /** * Query the size of a file within a storage container. @@ -230,34 +465,38 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); * \param storage a storage container to query. * \param path the relative path of the file to query. * \param length a pointer to be filled with the file's length. - * \returns SDL_TRUE if the file could be queried or SDL_FALSE on failure; - * call SDL_GetError() for more information. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); /** * Synchronously read a file from a storage container into a client-provided * buffer. * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * * \param storage a storage container to read from. * \param path the relative path of the file to read. * \param destination a client-provided buffer to read the file into. * \param length the length of the destination buffer. - * \returns SDL_TRUE if the file was read or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageFileSize * \sa SDL_StorageReady * \sa SDL_WriteStorageFile */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); /** * Synchronously write a file from client memory into a storage container. @@ -266,64 +505,73 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, c * \param path the relative path of the file to write. * \param source a client-provided buffer to write from. * \param length the length of the source buffer. - * \returns SDL_TRUE if the file was written or SDL_FALSE on failure; call + * \returns true if the file was written or false on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageSpaceRemaining * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); /** * Create a directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); /** * Enumerate a directory in a storage container through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); /** * Rename a file or directory in a writable storage container. @@ -331,14 +579,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Copy a file in a writable storage container. @@ -346,14 +594,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Get information about a filesystem path in a storage container. @@ -362,14 +610,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, c * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); /** * Queries the remaining space in a storage container. @@ -377,7 +625,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage * \param storage a storage container to query. * \returns the amount of remaining space, in bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -401,8 +649,11 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param pattern the pattern that files in the directory must match. Can be * NULL. * \param flags `SDL_GLOB_*` bitflags that affect this search. @@ -417,7 +668,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * \threadsafety It is safe to call this function from any thread, assuming * the `storage` object is thread-safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h index aafe574..0752f53 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,19 @@ /** * # CategorySurface * - * SDL_Surface definition and management functions. + * SDL surfaces are buffers of pixels in system RAM. These are useful for + * passing around and manipulating images that are not stored in GPU memory. + * + * SDL_Surface makes serious efforts to manage images in various formats, and + * provides a reasonable toolbox for transforming the data, including copying + * between surfaces, filling rectangles in the image data, etc. + * + * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not + * provide loaders for various other file formats, but there are several + * excellent external libraries that do, including its own satellite library, + * SDL_image: + * + * https://github.com/libsdl-org/SDL_image */ #ifndef SDL_surface_h_ @@ -47,7 +59,7 @@ extern "C" { * * These are generally considered read-only. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SurfaceFlags; @@ -59,14 +71,14 @@ typedef Uint32 SDL_SurfaceFlags; /** * Evaluates to true if the surface needs to be locked before access. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MUSTLOCK(S) ((((S)->flags & SDL_SURFACE_LOCK_NEEDED)) == SDL_SURFACE_LOCK_NEEDED) /** * The scaling mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ScaleMode { @@ -77,7 +89,7 @@ typedef enum SDL_ScaleMode /** * The flip mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlipMode { @@ -86,8 +98,7 @@ typedef enum SDL_FlipMode SDL_FLIP_VERTICAL /**< flip vertically */ } SDL_FlipMode; -/* Internal surface data */ -typedef struct SDL_SurfaceData SDL_SurfaceData; +#ifndef SDL_INTERNAL /** * A collection of pixels used in software blitting. @@ -104,22 +115,32 @@ typedef struct SDL_SurfaceData SDL_SurfaceData; * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * - * \since This struct is available since SDL 3.0.0. + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface */ -typedef struct SDL_Surface +struct SDL_Surface { - SDL_SurfaceFlags flags; /**< Read-only */ - SDL_PixelFormat format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-only pointer, writable pixels if non-NULL */ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ int refcount; /**< Application reference count, used when freeing surface */ - SDL_SurfaceData *internal; /**< Private */ - -} SDL_Surface; + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ +typedef struct SDL_Surface SDL_Surface; /** * Allocate a new surface with a specific pixel format. @@ -132,7 +153,7 @@ typedef struct SDL_Surface * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurfaceFrom * \sa SDL_DestroySurface @@ -160,7 +181,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurface(int width, int heigh * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -174,9 +195,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurfaceFrom(int width, int h * * \param surface the SDL_Surface to free. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_CreateStackSurface * \sa SDL_CreateSurface * \sa SDL_CreateSurfaceFrom */ @@ -206,7 +226,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface); @@ -221,16 +241,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac * interpreted in color operations. * * \param surface the SDL_Surface structure to update. - * \param colorspace an SDL_ColorSpace value describing the surface + * \param colorspace an SDL_Colorspace value describing the surface * colorspace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); /** * Get the colorspace used by a surface. @@ -243,7 +263,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surfa * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if * the surface is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorspace */ @@ -271,7 +291,7 @@ extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface * the surface didn't have an index format); call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -284,15 +304,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface * * * \param surface the SDL_Surface structure to update. * \param palette the SDL_Palette structure to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); /** * Get the palette used by a surface. @@ -301,7 +321,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, * \returns a pointer to the palette used by the surface, or NULL if there is * no palette used. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfacePalette */ @@ -321,31 +341,30 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \param surface the SDL_Surface structure to update. * \param image a pointer to an alternate SDL_Surface to associate with this * surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages * \sa SDL_SurfaceHasAlternateImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); /** * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true if alternate versions are available or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); /** * Get an array including all versions of a surface. @@ -364,7 +383,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface * * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -380,7 +399,7 @@ extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *sur * * \param surface the SDL_Surface structure to update. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_GetSurfaceImages @@ -401,22 +420,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s * format of the surface will not change. * * \param surface the SDL_Surface structure to be locked. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockSurface(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); /** * Release a surface after directly accessing the pixels. * * \param surface the SDL_Surface structure to be unlocked. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSurface */ @@ -429,18 +448,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * will result in a memory leak. * * \param src the data stream for the surface. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); /** * Load a BMP image from a file. @@ -452,7 +471,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP_IO @@ -471,17 +490,17 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); * * \param surface the SDL_Surface structure containing the image to be saved. * \param dst a data stream to save to. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, - * even in the case of an error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closeio if true, calls SDL_CloseIO() on `dst` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, SDL_bool closeio); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); /** * Save a surface to a file. @@ -494,15 +513,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IO * * \param surface the SDL_Surface structure containing the image to be saved. * \param file a file to save to. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); /** * Set the RLE acceleration hint for a surface. @@ -511,32 +530,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const cha * the surface must be locked before directly accessing the pixels. * * \param surface the SDL_Surface structure to optimize. - * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable - * it. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable RLE acceleration, false to disable it. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface * \sa SDL_LockSurface * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); /** * Returns whether the surface is RLE enabled. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. + * \returns true if the surface is RLE enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceRLE */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); /** * Set the color key (transparent pixel) in a surface. @@ -549,34 +567,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * SDL_MapRGB(). * * \param surface the SDL_Surface structure to update. - * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color - * key. + * \param enabled true to enable color key, false to disable color key. * \param key the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorKey * \sa SDL_SetSurfaceRLE * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); /** * Returns whether the surface has a color key. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. + * \returns true if the surface has a color key, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); /** * Get the color key (transparent pixel) for a surface. @@ -584,19 +601,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface * The color key is a pixel of the format used by the surface, as generated by * SDL_MapRGB(). * - * If the surface doesn't have color key enabled this function returns -1. + * If the surface doesn't have color key enabled this function returns false. * * \param surface the SDL_Surface structure to query. * \param key a pointer filled in with the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); /** * Set an additional color value multiplied into blit operations. @@ -611,15 +628,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface * \param r the red color value multiplied into blit operations. * \param g the green color value multiplied into blit operations. * \param b the blue color value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); /** @@ -629,15 +646,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); /** * Set an additional alpha value used in blit operations. @@ -649,30 +666,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param alpha the alpha value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); /** * Get the additional alpha value used in blit operations. * * \param surface the SDL_Surface structure to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); /** * Set the blend mode used for blit operations. @@ -683,28 +700,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); /** * Get the blend mode used for blit operations. * * \param surface the SDL_Surface structure to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); /** * Set the clipping rectangle for a surface. @@ -718,14 +735,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surfac * \param surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); /** * Get the clipping rectangle for a surface. @@ -737,26 +754,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for * the surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); /** * Flip a surface vertically or horizontally. * * \param surface the surface to flip. * \param flip the direction to flip. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); /** * Creates a new surface identical to the existing surface. @@ -770,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_F * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -789,7 +806,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surf * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -814,7 +831,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface, * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurfaceAndColorspace * \sa SDL_DestroySurface @@ -840,10 +857,9 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurface - * \sa SDL_ConvertSurface * \sa SDL_DestroySurface */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props); @@ -859,14 +875,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Su * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixelsAndColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); /** * Copy a block of pixels of one format and colorspace to another format and @@ -875,27 +891,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SD * \param width the width of the block to copy, in pixels. * \param height the height of the block to copy, in pixels. * \param src_format an SDL_PixelFormat value of the `src` pixels format. - * \param src_colorspace an SDL_ColorSpace value describing the colorspace of + * \param src_colorspace an SDL_Colorspace value describing the colorspace of * the `src` pixels. * \param src_properties an SDL_PropertiesID with additional source color * properties, or 0. * \param src a pointer to the source pixels. * \param src_pitch the pitch of the source pixels, in bytes. * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. - * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of * the `dst` pixels. * \param dst_properties an SDL_PropertiesID with additional destination color * properties, or 0. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixels */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); /** * Premultiply the alpha on a block of pixels. @@ -910,14 +926,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, i * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with premultiplied pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); /** * Premultiply the alpha in a surface. @@ -925,14 +941,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, * This is safe to use with src == dst, but not for other overlapping areas. * * \param surface the surface to modify. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); /** * Clear a surface with a specific color, with floating point precision. @@ -947,12 +963,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *su * \param g the green component of the pixel, normally in the range 0-1. * \param b the blue component of the pixel, normally in the range 0-1. * \param a the alpha component of the pixel, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); /** * Perform a fast fill of a rectangle with a specific color. @@ -970,14 +986,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, floa * \param rect the SDL_Rect structure representing the rectangle to fill, or * NULL to fill the entire surface. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); /** * Perform a fast fill of a set of rectangles with a specific color. @@ -995,22 +1011,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const * \param rects an array of SDL_Rects representing the rectangles to fill. * \param count the number of rectangles in the array. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); /** - * Performs a fast blit from the source surface to the destination surface. + * Performs a fast blit from the source surface to the destination surface + * with clipping. * - * This assumes that the source and destination rectangles are the same size. * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or - * `dst`) is copied. The final blit rectangles are saved in `srcrect` and - * `dstrect` after all clipping is performed. + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. + * + * The final blit rectangles are saved in `srcrect` and `dstrect` after all + * clipping is performed. * * The blit function should not be called on a locked surface. * @@ -1066,18 +1084,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, cons * height are ignored, and are copied from `srcrect`. If you * want a specific width and height, you should use * SDL_BlitSurfaceScaled(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform low-level surface blitting only. @@ -1091,18 +1109,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit to a destination surface, which may be of a different @@ -1116,18 +1134,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, * the destination surface, or NULL to fill the entire * destination surface. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform low-level surface scaled blitting only. @@ -1142,18 +1160,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, con * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform a tiled blit to a destination surface, which may be of a different @@ -1168,18 +1186,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled and tiled blit to a destination surface, which may be of a @@ -1198,18 +1216,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, cons * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit using the 9-grid algorithm to a destination surface, @@ -1235,18 +1253,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface * * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Map an RGB triple to an opaque pixel value for a surface. @@ -1272,7 +1290,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, cons * \param b the blue component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGBA */ @@ -1303,7 +1321,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 * \param a the alpha component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGB */ @@ -1329,12 +1347,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint * ignore this channel. * \param a a pointer filled in with the alpha channel, 0-255, or NULL to * ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Retrieves a single pixel from a surface. @@ -1353,12 +1371,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, * 0-1, or NULL to ignore this channel. * \param a a pointer filled in with the alpha channel, normally in the range * 0-1, or NULL to ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); /** * Writes a single pixel to a surface. @@ -1376,12 +1394,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surf * \param g the green channel value, 0-255. * \param b the blue channel value, 0-255. * \param a the alpha channel value, 0-255. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Writes a single pixel to a surface. @@ -1396,12 +1414,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, * \param g the green channel value, normally in the range 0-1. * \param b the blue channel value, normally in the range 0-1. * \param a the alpha channel value, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h index 17ac0a1..294089f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,13 @@ /** * # CategorySystem * - * Platform-specific SDL API functions. + * Platform-specific SDL API functions. These are functions that deal with + * needs of specific operating systems, that didn't make sense to offer as + * platform-independent, generic APIs. + * + * Most apps can make do without these functions, but they can be useful for + * integrating with other parts of a specific system, adding platform-specific + * polish to an app, or solving problems that only affect one target. */ #ifndef SDL_system_h_ @@ -31,7 +37,6 @@ #include #include #include -#include #include #include @@ -44,16 +49,15 @@ extern "C" { /* * Platform specific functions for Windows */ -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) typedef struct tagMSG MSG; /** * A callback to be used with SDL_SetWindowsMessageHook. * - * This callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * This callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * As this is processing a message directly from the Windows event loop, this * callback should do the minimum required work and return quickly. @@ -61,36 +65,35 @@ typedef struct tagMSG MSG; * \param userdata the app-defined pointer provided to * SDL_SetWindowsMessageHook. * \param msg a pointer to a Win32 event structure to process. - * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it. + * \returns true to let event continue on, false to drop it. * * \threadsafety This may only be called (by SDL) from the thread handling the * Windows event loop. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetWindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ -typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); /** * Set a callback for every Windows message, run before TranslateMessage(). * - * The callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_WindowsMessageHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) @@ -104,14 +107,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo * \returns the D3D9 adapter index on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ - -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) - /** * Get the DXGI Adapter and Output indices for the specified display. * @@ -122,33 +121,55 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displ * \param displayID the instance of the display to query. * \param adapterIndex a pointer to be filled in with the adapter index. * \param outputIndex a pointer to be filled in with the output index. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + /* * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _XEvent XEvent; -typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); + +/** + * A callback to be used with SDL_SetX11EventHook. + * + * This callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * As this is processing an event directly from the X11 event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to SDL_SetX11EventHook. + * \param xevent a pointer to an Xlib XEvent union to process. + * \returns true to let event continue on, false to drop it. + * + * \threadsafety This may only be called (by SDL) from the thread handling the + * X11 event loop. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetX11EventHook + */ +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** * Set a callback for every X11 event. * - * The callback may modify the event, and should return SDL_TRUE if the event - * should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_X11EventHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); @@ -162,12 +183,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, * * \param threadID the Unix thread ID to change priority of. * \param priority the new, Unix-specific, priority value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); /** * Sets the priority (not nice level) and scheduling policy for a thread. @@ -178,12 +199,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, * \param sdlPriority the new SDL_ThreadPriority value. * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, * SCHED_OTHER, etc...). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); #endif /* SDL_PLATFORM_LINUX */ @@ -204,7 +225,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 * \param userdata what was passed as `callbackParam` to * SDL_SetiOSAnimationCallback as `callbackParam`. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ @@ -240,27 +261,27 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSEventPump */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); /** * Use this function to enable or disable the SDL event pump on Apple iOS. * * This function is only available on Apple iOS. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. + * \param enabled true to enable the event pump, false to disable it. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); #endif /* SDL_PLATFORM_IOS */ @@ -286,7 +307,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidActivity */ @@ -311,7 +332,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidJNIEnv */ @@ -349,43 +370,34 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); * * \returns the Android API level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - /** * Query if the application is running on a Chromebook. * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * \returns true if this is a Chromebook, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); /** * Query if the application is running on a Samsung DeX docking station. * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * \returns true if this is a DeX docking station, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); /** * Trigger the Android system back button behavior. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); @@ -393,9 +405,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * See the official Android developer guide for more information: * http://developer.android.com/guide/topics/data/data-storage.html * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 + +/** + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -414,9 +433,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \returns the path used for internal storage or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidExternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void); @@ -431,7 +451,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void) * \returns the current state of external storage, or 0 if external storage is * currently unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStoragePath */ @@ -453,9 +473,11 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); * \returns the path used for external storage for this application on success * or NULL on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void); @@ -474,12 +496,25 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) * \returns the path used for caches for this application on success or NULL * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidExternalStoragePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - -typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted); +/** + * Callback that presents a response from a SDL_RequestAndroidPermission call. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param permission the Android-specific permission name that was requested. + * \param granted true if permission is granted, false if denied. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RequestAndroidPermission + */ +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** * Request permissions at runtime, asynchronously. @@ -500,18 +535,22 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * like memory running out. Normally there will be a yes or no to the request * through the callback. * + * For the `permission` parameter, choose a value from here: + * + * https://developer.android.com/reference/android/Manifest.permission + * * \param permission the permission to request. * \param cb the callback to trigger when the request has a response. * \param userdata an app-controlled pointer that is passed to the callback. - * \returns SDL_TRUE if the request was submitted, SDL_FALSE if there was an - * error submitting. The result of the request is only ever reported + * \returns true if the request was submitted, false if there was an error + * submitting. The result of the request is only ever reported * through the callback, not this return value. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); /** * Shows an Android toast notification. @@ -532,14 +571,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *pe * \param gravity where the notification should appear on the screen. * \param xoffset set this parameter only when gravity >=0. * \param yoffset set this parameter only when gravity >=0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); /** * Send a user command to SDLActivity. @@ -548,111 +587,63 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, i * * \param command user command that must be greater or equal to 0x8000. * \param param user parameter. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); #endif /* SDL_PLATFORM_ANDROID */ -/* - * Platform specific functions for WinRT - */ -#ifdef SDL_PLATFORM_WINRT - -/** - * WinRT / Windows Phone path types - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_Path -{ - /** The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily(); - -#endif /* SDL_PLATFORM_WINRT */ - /** * Query if the current device is a tablet. * - * If SDL can't determine this, it will return SDL_FALSE. + * If SDL can't determine this, it will return false. * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * \returns true if the device is a tablet, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_Sandbox +{ + SDL_SANDBOX_NONE = 0, + SDL_SANDBOX_UNKNOWN_CONTAINER, + SDL_SANDBOX_FLATPAK, + SDL_SANDBOX_SNAP, + SDL_SANDBOX_MACOS +} SDL_Sandbox; + +/** + * Get the application sandbox environment, if any. + * + * \returns the application sandbox environment or SDL_SANDBOX_NONE if the + * application is not running in a sandbox environment. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void); + /* Functions used by iOS app delegates to notify SDL about state changes. */ @@ -669,7 +660,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); @@ -686,7 +677,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); @@ -703,7 +694,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); @@ -720,7 +711,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); @@ -737,7 +728,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); @@ -754,7 +745,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); @@ -773,7 +764,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); #endif @@ -794,12 +785,12 @@ typedef struct XUser *XUserHandle; * leak. * * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); /** * Gets a reference to the default user handle for GDK. @@ -809,12 +800,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTa * * \param outUserHandle a pointer to be filled in with the default user * handle. - * \returns SDL_TRUE if success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); #endif diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h index 0fdc8a0..277535f 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,19 @@ /** * # CategoryThread * - * SDL thread management routines. + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. */ #include @@ -34,9 +46,8 @@ /* Thread synchronization primitives */ #include -#include -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +#if defined(SDL_PLATFORM_WINDOWS) #include /* _beginthreadex() and _endthreadex() */ #endif @@ -51,7 +62,7 @@ extern "C" { * * These are opaque data. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -65,7 +76,7 @@ typedef struct SDL_Thread SDL_Thread; * application will operate on, but having a way to uniquely identify a thread * can be useful at times. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetThreadID * \sa SDL_GetCurrentThreadID @@ -78,7 +89,7 @@ typedef Uint64 SDL_ThreadID; * 0 is the invalid ID. An app can create these and then set data for these * IDs that is unique to each thread. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetTLS * \sa SDL_SetTLS @@ -90,11 +101,11 @@ typedef SDL_AtomicInt SDL_TLSID; * * SDL will make system changes as necessary in order to apply the thread * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, @@ -103,13 +114,30 @@ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_TIME_CRITICAL } SDL_ThreadPriority; +/** + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + */ +typedef enum SDL_ThreadState +{ + SDL_THREAD_UNKNOWN, /**< The thread is not valid */ + SDL_THREAD_ALIVE, /**< The thread is currently running */ + SDL_THREAD_DETACHED, /**< The thread is detached and can't be waited on */ + SDL_THREAD_COMPLETE /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} SDL_ThreadState; + /** * The function passed to SDL_CreateThread() as the new thread's entry point. * * \param data what was passed as `data` to SDL_CreateThread(). * \returns a value that can be reported through SDL_WaitThread(). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -179,7 +207,7 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThreadWithProperties * \sa SDL_WaitThread @@ -245,7 +273,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -263,7 +291,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop /* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ #ifndef SDL_WIKI_DOCUMENTATION_SECTION -# if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +# if defined(SDL_PLATFORM_WINDOWS) # ifndef SDL_BeginThreadFunction # define SDL_BeginThreadFunction _beginthreadex # endif @@ -300,7 +328,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -314,7 +342,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunct * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -334,7 +362,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S * \returns a pointer to a UTF-8 string that names the specified thread, or * NULL if it doesn't have a name. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); @@ -350,7 +378,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); * * \returns the ID of the current thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetThreadID */ @@ -367,7 +395,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentThreadID */ @@ -381,25 +409,25 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * an administrator account. Be prepared for this to fail. * * \param priority the SDL_ThreadPriority to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); /** * Wait for a thread to finish. * - * Threads that haven't been detached will remain (as a "zombie") until this - * function cleans them up. Not doing so is a resource leak. + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. * * Once a thread has been cleaned up through this function, the SDL_Thread * that references it becomes invalid and should not be referenced again. As * such, only one thread may call SDL_WaitThread() on another. * - * The return code for the thread function is placed in the area pointed to by - * `status`, if `status` is not NULL. + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. * * You may not wait on a thread that has been used in a call to * SDL_DetachThread(). Use either that function or this one, but not both, or @@ -412,17 +440,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority pr * * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. - * \param status pointer to an integer that will receive the value returned - * from the thread function by its 'return', or NULL to not - * receive such value back. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_DetachThread */ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status); +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *thread); + /** * Let a thread clean up on exit without intervention. * @@ -452,7 +493,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status) * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -468,7 +509,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread *thread); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -481,7 +522,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetTLS(SDL_TLSID *id); * * \param value a pointer previously handed to SDL_SetTLS. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -504,16 +545,16 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * \param value the value to associate with the ID for the current thread. * \param destructor a function called when the thread exits, to free the * value, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTLS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. @@ -524,7 +565,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CleanupTLS(void); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h index 86c1fad..b6d3f6d 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ freely, subject to the following restrictions: * # CategoryTime * * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. */ #include @@ -41,7 +49,7 @@ extern "C" { * A structure holding a calendar date and time broken down into its * components. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DateTime { @@ -59,7 +67,7 @@ typedef struct SDL_DateTime /** * The preferred date format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -73,7 +81,7 @@ typedef enum SDL_DateFormat /** * The preferred time format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -95,24 +103,24 @@ typedef enum SDL_TimeFormat * format, may be NULL. * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * format, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); /** * Gets the current value of the system realtime clock in nanoseconds since * Jan 1, 1970 in Universal Coordinated Time (UTC). * * \param ticks the SDL_Time to hold the returned tick count. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); /** * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in @@ -123,12 +131,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \param localTime the resulting SDL_DateTime will be expressed in local time * if true, otherwise it will be in Universal Coordinated * Time (UTC). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime); +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); /** * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. @@ -138,12 +146,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_Date * * \param dt the source SDL_DateTime. * \param ticks the resulting SDL_Time. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); /** * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals @@ -157,7 +165,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, * \param dwHighDateTime a pointer filled in with the high portion of the * Windows FILETIME value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); @@ -172,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow * \param dwHighDateTime the high portion of the Windows FILETIME value. * \returns the converted SDL time. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); @@ -184,7 +192,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * \returns the number of days in the requested month or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); @@ -197,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \returns the day of year [0-365] if the date is valid or -1 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); @@ -210,7 +218,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or * -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h index 9d05161..cf94881 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,20 @@ /** * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. */ #include @@ -38,16 +51,137 @@ extern "C" { #endif /* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_US 1000 + +/** + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND) + +/** + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND) + +/** + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS) + +/** + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS) + +/** + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US) + +/** + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) /** @@ -56,7 +190,9 @@ extern "C" { * \returns an unsigned 64-bit value representing the number of milliseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); @@ -66,7 +202,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); * \returns an unsigned 64-bit value representing the number of nanoseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); @@ -81,7 +219,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); * * \returns the current counter value. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceFrequency */ @@ -92,7 +232,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); * * \returns a platform-specific count per second. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceCounter */ @@ -107,10 +249,33 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * * \param ms the number of milliseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); + /** * Wait a specified number of nanoseconds before returning. * @@ -120,14 +285,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * * \param ns the number of nanoseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS */ -extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); +extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); /** * Definition of the timer ID type. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_TimerID; @@ -151,7 +321,7 @@ typedef Uint32 SDL_TimerID; * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimer */ @@ -160,8 +330,6 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimer() call and should return the next * timer interval. If the value returned from the callback is 0, the timer is @@ -188,7 +356,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimerNS * \sa SDL_RemoveTimer @@ -215,7 +383,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimerNS */ @@ -224,8 +392,6 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimerNS() call and should return the * next timer interval. If the value returned from the callback is 0, the @@ -252,7 +418,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer * \sa SDL_RemoveTimer @@ -263,14 +429,16 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * Remove a timer created with SDL_AddTimer(). * * \param id the ID of the timer to remove. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h index 6889f36..64845a1 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryTouch * - * SDL touch management. + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. */ #ifndef SDL_touch_h_ @@ -31,7 +42,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -39,25 +49,53 @@ extern "C" { #endif +/** + * A unique ID for a touch device. + * + * This ID is valid for the time the device is connected to the system, and is + * never reused for the lifetime of the application. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_TouchID; + +/** + * A unique ID for a single finger on a touch device. + * + * This ID is valid for the time the finger (stylus, etc) is touching and will + * be unique for all fingers currently in contact, so this ID tracks the + * lifetime of a single continuous touch. This value may represent an index, a + * pointer, or some other unique ID, depending on the platform. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_FingerID; +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_TouchDeviceType { SDL_TOUCH_DEVICE_INVALID = -1, - SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ + SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */ } SDL_TouchDeviceType; /** * Data about a single finger in a multitouch event. * - * Each touch even is a collection of fingers that are simultaneously in + * Each touch event is a collection of fingers that are simultaneously in * contact with the touch device (so a "touch" can be a "multitouch," in * reality), and this struct reports details of the specific fingers. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetTouchFingers */ @@ -69,10 +107,18 @@ typedef struct SDL_Finger float pressure; /**< the quantity of pressure applied, normalized (0...1) */ } SDL_Finger; -/* Used as the device ID for mouse events simulated with touch input */ +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) -/* Used as the SDL_TouchID for touch events simulated with mouse input */ +/** + * The SDL_TouchID for touch events simulated with mouse input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) @@ -89,7 +135,7 @@ typedef struct SDL_Finger * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); @@ -100,7 +146,7 @@ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); * \returns touch device name, or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID); @@ -110,7 +156,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touc * \param touchID the ID of a touch device. * \returns touch device type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); @@ -125,7 +171,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_tray.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_tray.h new file mode 100644 index 0000000..0b05db2 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryTray + * + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. + */ + +#ifndef SDL_tray_h_ +#define SDL_tray_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Tray SDL_Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayMenu SDL_TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayEntry SDL_TrayEntry; + +/** + * Flags that control the creation of system tray entries. + * + * Some of these flags are required; exactly one of them must be specified at + * the time a tray entry is created. Other flags are optional; zero or more of + * those can be OR'ed together with the required flag. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +typedef Uint32 SDL_TrayEntryFlags; + +#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */ +#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */ +#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */ +#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */ +#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */ + +/** + * A callback that is invoked when a tray entry is selected. + * + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param entry the tray entry that was selected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTrayEntryCallback + */ +typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); + +/** + * Create an icon to be placed in the operating system's tray, or equivalent. + * + * Many platforms advise not using a system tray unless persistence is a + * necessary feature. Avoid needlessly creating a tray icon, as the user may + * feel like it clutters their interface. + * + * Using tray icons require the video subsystem. + * + * \param icon a surface to be used as icon. May be NULL. + * \param tooltip a tooltip to be displayed when the mouse hovers the icon in + * UTF-8 encoding. Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenu + * \sa SDL_DestroyTray + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip); + +/** + * Updates the system tray icon's icon. + * + * \param tray the tray icon to be updated. + * \param icon the new icon. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon); + +/** + * Updates the system tray icon's tooltip. + * + * \param tray the tray icon to be updated. + * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip); + +/** + * Create a menu for a system tray. + * + * This should be called at most once per tray icon. + * + * This function does the same thing as SDL_CreateTraySubmenu(), except that + * it takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_GetTrayMenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); + +/** + * Create a submenu for a system tray entry. + * + * This should be called at most once per tray entry. + * + * This function does the same thing as SDL_CreateTrayMenu, except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTraySubmenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry); + +/** + * Gets a previously created tray menu. + * + * You should have called SDL_CreateTrayMenu() on the tray object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTraySubmenu(), except that it + * takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_CreateTrayMenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); + +/** + * Gets a previously created tray entry submenu. + * + * You should have called SDL_CreateTraySubmenu() on the entry object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTrayMenu(), except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_CreateTraySubmenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry); + +/** + * Returns a list of entries in the menu, in order. + * + * \param menu The menu to get entries from. + * \param size An optional pointer to obtain the number of entries in the + * menu. + * \returns a NULL-terminated list of entries within the given menu. The + * pointer becomes invalid when any function that inserts or deletes + * entries in the menu is called. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveTrayEntry + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size); + +/** + * Removes a tray entry. + * + * \param entry The entry to be deleted. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); + +/** + * Insert a tray entry at a given position. + * + * If label is NULL, the entry will be a separator. Many functions won't work + * for an entry that is a separator. + * + * An entry does not need to be destroyed; it will be destroyed with the tray. + * + * \param menu the menu to append the entry to. + * \param pos the desired position for the new entry. Entries at or following + * this place will be moved. If pos is -1, the entry is appended. + * \param label the text to be displayed on the entry, in UTF-8 encoding, or + * NULL for a separator. + * \param flags a combination of flags, some of which are mandatory. + * \returns the newly created entry, or NULL if pos is out of bounds. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TrayEntryFlags + * \sa SDL_GetTrayEntries + * \sa SDL_RemoveTrayEntry + * \sa SDL_GetTrayEntryParent + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags); + +/** + * Sets the label of an entry. + * + * An entry cannot change between a separator and an ordinary entry; that is, + * it is not possible to set a non-NULL label on an entry that has a NULL + * label (separators), or to set a NULL label to an entry that has a non-NULL + * label. The function will silently fail if that happens. + * + * \param entry the entry to be updated. + * \param label the new label for the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryLabel + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label); + +/** + * Gets the label of an entry. + * + * If the returned value is NULL, the entry is a separator. + * + * \param entry the entry to be read. + * \returns the label of the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryLabel + */ +extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be updated. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryChecked + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked); + +/** + * Gets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be read. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryChecked + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is enabled. + * + * \param entry the entry to be updated. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled); + +/** + * Gets whether or not an entry is enabled. + * + * \param entry the entry to be read. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); + +/** + * Sets a callback to be invoked when the entry is selected. + * + * \param entry the entry to be updated. + * \param callback a callback to be invoked when the entry is selected. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata); + +/** + * Simulate a click on a tray entry. + * + * \param entry The entry to activate. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); + +/** + * Gets the menu containing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry); + +/** + * Gets the entry for which the menu is a submenu, if the current menu is a + * submenu. + * + * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent entry. + * \returns the parent entry, or NULL if this menu is not a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTraySubmenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu); + +/** + * Gets the tray for which this menu is the first-level menu, if the current + * menu isn't a submenu. + * + * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent enttrayry. + * \returns the parent tray, or NULL if this menu is a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); + +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h index c0f518d..55014e3 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -30,7 +30,6 @@ #define SDL_version_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -43,7 +42,7 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 3. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MAJOR_VERSION 3 @@ -52,18 +51,18 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 2. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MINOR_VERSION 1 +#define SDL_MINOR_VERSION 2 /** * The current micro (or patchlevel) version of the SDL headers. * * If this were SDL version 3.2.1, this value would be 1. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MICRO_VERSION 2 +#define SDL_MICRO_VERSION 0 /** * This macro turns the version numbers into a numeric value. @@ -74,7 +73,7 @@ extern "C" { * \param minor the minorversion number. * \param patch the patch version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM(major, minor, patch) \ ((major) * 1000000 + (minor) * 1000 + (patch)) @@ -86,7 +85,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) @@ -97,7 +96,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) @@ -108,14 +107,16 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) /** * This is the version number macro for the current SDL version. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion */ #define SDL_VERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION) @@ -123,7 +124,7 @@ extern "C" { /** * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ (SDL_VERSION >= SDL_VERSIONNUM(X, Y, Z)) @@ -140,7 +141,7 @@ extern "C" { * * \returns the version of the linked library. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRevision */ @@ -166,7 +167,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); * \returns an arbitrary string, uniquely identifying the exact revision of * the SDL library in use. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVersion */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h index 7cce828..a7afc32 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,28 @@ /** * # CategoryVideo * - * SDL video functions. + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). */ #ifndef SDL_video_h_ @@ -49,7 +70,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_DisplayID; @@ -58,7 +79,7 @@ typedef Uint32 SDL_DisplayID; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_WindowID; @@ -82,7 +103,7 @@ typedef Uint32 SDL_WindowID; /** * System theme. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemTheme { @@ -91,13 +112,21 @@ typedef enum SDL_SystemTheme SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ } SDL_SystemTheme; -/* Internal display mode data */ +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** * The structure that defines a display mode. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetFullscreenDisplayModes * \sa SDL_GetDesktopDisplayMode @@ -123,7 +152,7 @@ typedef struct SDL_DisplayMode /** * Display orientation values; the way a display is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_DisplayOrientation { @@ -137,7 +166,7 @@ typedef enum SDL_DisplayOrientation /** * The struct used as an opaque handle to a window. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateWindow */ @@ -151,7 +180,7 @@ typedef struct SDL_Window SDL_Window; * changed on existing windows by the app, and some of it might be altered by * the user or system outside of the app's control. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ @@ -185,31 +214,91 @@ typedef Uint64 SDL_WindowFlags; /** - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. * - * \since This macro is available since SDL 3.0.0. + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u + +/** + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) + +/** + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A magic value used with SDL_WINDOWPOS_CENTERED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u /** * Used to indicate that the window position should be centered. * - * \since This macro is available since SDL 3.0.0. + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. */ -#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) + +/** + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlashOperation { @@ -221,30 +310,102 @@ typedef enum SDL_FlashOperation /** * An opaque handle to an OpenGL context. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef int SDL_EGLint; /** - * EGL attribute initialization callback types. + * EGL platform attribute initialization callback. * - * \since This datatype is available since SDL 3.0.0. + * This is called when SDL is attempting to create an EGL context, to let the + * app add extra attributes to its eglGetPlatformDisplay() call. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks */ -typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); -typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); /** * An enumeration of OpenGL configuration attributes. @@ -261,9 +422,9 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); * fail if the GL can't provide your requested attributes at a minimum, but * you should check to see exactly what you got. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ -typedef enum SDL_GLattr +typedef enum SDL_GLAttr { SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ @@ -284,64 +445,64 @@ typedef enum SDL_GLattr SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ - SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ - SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLcontextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS, SDL_GL_EGL_PLATFORM -} SDL_GLattr; +} SDL_GLAttr; /** * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLprofile -{ - SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, - SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, - SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ -} SDL_GLprofile; +typedef Uint32 SDL_GLProfile; + +#define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */ +#define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */ +#define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ + /** - * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextFlag -{ - SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, - SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, - SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG = 0x0004, - SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 -} SDL_GLcontextFlag; +typedef Uint32 SDL_GLContextFlag; + +#define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001 +#define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002 +#define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004 +#define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008 + /** * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR * attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextReleaseFlag -{ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 -} SDL_GLcontextReleaseFlag; +typedef Uint32 SDL_GLContextReleaseFlag; + +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000 +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001 + /** * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLContextResetNotification -{ - SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, - SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 -} SDL_GLContextResetNotification; +typedef Uint32 SDL_GLContextResetNotification; + +#define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000 +#define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001 + /* Function prototypes */ @@ -350,7 +511,9 @@ typedef enum SDL_GLContextResetNotification * * \returns the number of built in video drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVideoDriver */ @@ -369,7 +532,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers */ @@ -385,7 +550,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); * \returns the name of the current video driver or NULL if no driver has been * initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers * \sa SDL_GetVideoDriver @@ -397,7 +564,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); * * \returns the current system theme, light, dark, or unknown. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); @@ -410,7 +579,9 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); @@ -420,7 +591,9 @@ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); * \returns the instance ID of the primary display on success or 0 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -448,7 +621,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); @@ -462,7 +637,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa * \returns the name of a display or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -471,19 +648,22 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa /** * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the usable desktop area represented by a display, in screen @@ -499,15 +679,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayI * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the orientation of a display when it is unrotated. @@ -516,7 +698,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID di * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -529,7 +713,9 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -543,12 +729,21 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays */ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID); @@ -573,7 +768,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -587,7 +784,7 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * refresh rate default to the desktop mode if they are set to 0. The modes * are scanned with size being first priority, format being second priority, * and finally checking the refresh rate. If all the available modes are too - * small, then NULL is returned. + * small, then false is returned. * * \param displayID the instance ID of the display to query. * \param w the width in pixels of the desired display mode. @@ -596,17 +793,19 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * for the desktop refresh rate. * \param include_high_density_modes boolean to include high density modes in * the search. - * \param mode a pointer filled in with the closest display mode equal to or - * larger than the desired mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closest a pointer filled in with the closest display mode equal to + * or larger than the desired mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes, SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest); /** * Get information about the desktop's display mode. @@ -620,7 +819,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Dis * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayMode * \sa SDL_GetDisplays @@ -639,7 +840,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDisplays @@ -653,7 +856,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SD * \returns the instance ID of the display containing the point or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -668,7 +873,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point * closest to the center of the rect on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -683,7 +890,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect * * on success or 0 on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -701,7 +910,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowDisplayScale */ @@ -725,7 +936,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window); * \returns the display scale, or 0.0f on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); @@ -743,24 +956,26 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * taken effect. * * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an - * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new - * mode dimensions. + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode + * dimensions. * * \param window the window to affect. * \param mode a pointer to the display mode to use, which can be NULL for * borderless fullscreen desktop mode, or one of the fullscreen * modes returned by SDL_GetFullscreenDisplayModes() to set an * exclusive fullscreen mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreen * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); /** * Query the display mode to use when a window is visible at fullscreen. @@ -769,7 +984,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *win * \returns a pointer to the exclusive fullscreen mode to use or NULL for * borderless fullscreen desktop mode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -785,7 +1002,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode( * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); @@ -797,7 +1016,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); @@ -811,7 +1032,9 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); @@ -870,7 +1093,7 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). * * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. * * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, * SDL_CreateWindow() will fail. @@ -890,8 +1113,11 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindowAndRenderer * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindowWithProperties * \sa SDL_DestroyWindow @@ -901,36 +1127,41 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int /** * Create a child popup window of the specified parent window. * - * 'flags' **must** contain exactly one of the following: - - * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any - * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu. - * The topmost popup menu will implicitly gain the keyboard focus. + * The flags parameter **must** contain at least one of the following: + * + * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any + * input events. + * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost + * popup menu will implicitly gain the keyboard focus. * * The following flags are not relevant to popup window creation and will be * ignored: * - * - 'SDL_WINDOW_MINIMIZED' - * - 'SDL_WINDOW_MAXIMIZED' - * - 'SDL_WINDOW_FULLSCREEN' - * - 'SDL_WINDOW_BORDERLESS' + * - `SDL_WINDOW_MINIMIZED` + * - `SDL_WINDOW_MAXIMIZED` + * - `SDL_WINDOW_FULLSCREEN` + * - `SDL_WINDOW_BORDERLESS` + * + * The following flags are incompatible with popup window creation and will + * cause it to fail: + * + * - `SDL_WINDOW_UTILITY` + * - `SDL_WINDOW_MODAL` * * The parent parameter **must** be non-null and a valid window. The parent of * a popup window can be either a regular, toplevel window, or another popup * window. * * Popup windows cannot be minimized, maximized, made fullscreen, raised, - * flash, be made a modal window, be the parent of a modal window, or grab the - * mouse and/or keyboard. Attempts to do so will fail. + * flash, be made a modal window, be the parent of a toplevel window, or grab + * the mouse and/or keyboard. Attempts to do so will fail. * * Popup windows implicitly do not have a border/decorations and do not appear * on the taskbar/dock or in lists of windows such as alt-tab menus. * - * If a parent window is hidden, any child popup windows will be recursively - * hidden as well. Child popup windows not explicitly hidden will be restored - * when the parent is shown. - * - * If the parent window is destroyed, any child popup windows will be - * recursively destroyed as well. + * If a parent window is hidden or destroyed, any child popup windows will be + * recursively hidden or destroyed as well. Child popup windows not explicitly + * hidden will be restored when the parent is shown. * * \param parent the parent of the window, must not be NULL. * \param offset_x the x position of the popup window relative to the origin @@ -944,7 +1175,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_CreateWindowWithProperties @@ -987,7 +1220,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used * with OpenGL rendering * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the - * parent of this window, required for windows with the "toolip", "menu", + * parent of this window, required for windows with the "tooltip", "menu", * and "modal" properties * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be * resizable @@ -1003,10 +1236,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * * These are additional supported properties on macOS: * @@ -1024,8 +1259,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * [README/wayland](README/wayland) for more information on using custom * surfaces. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the - * application wants an associated `wl_egl_window` object to be created, - * even if the window does not have the OpenGL property or flag set. + * application wants an associated `wl_egl_window` object to be created and + * attached to the window, even if the window does not have the OpenGL + * property or `SDL_WINDOW_OPENGL` flag set. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface * associated with the window, if you want to wrap an existing window. See * [README/wayland](README/wayland) for more information. @@ -1061,7 +1297,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateWindow @@ -1114,7 +1352,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFromID */ @@ -1130,7 +1370,9 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window); * \returns the window associated with `id` or NULL if it doesn't exist; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowID */ @@ -1143,7 +1385,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id); * \returns the parent of the window on success or NULL if the window has no * parent. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow */ @@ -1181,7 +1425,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)` * UIWindow associated with the window * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag - * assocated with metal views on the window + * associated with metal views on the window * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's * framebuffer object. It must be bound when rendering to the screen using * OpenGL. @@ -1206,6 +1450,11 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag * assocated with metal views on the window * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the + * associated overlay window. + * * On Vivante: * * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType @@ -1215,11 +1464,6 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with * the window * - * On UWP: - * - * - `SDL_PROP_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow - * associated with the window - * * On Windows: * * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window @@ -1237,6 +1481,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * the window * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window * associated with the window * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated @@ -1263,7 +1509,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); @@ -1283,15 +1531,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window #define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev" #define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window" #define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag" +#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id" #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" -#define SDL_PROP_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window" #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" #define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display" #define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface" +#define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport" #define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window" #define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface" #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel" @@ -1308,7 +1557,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window * \param window the window to query. * \returns a mask of the SDL_WindowFlags associated with `window`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_HideWindow @@ -1327,14 +1578,16 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * * \param window the window to change. * \param title the desired window title in UTF-8 format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowTitle */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); /** * Get the title of a window. @@ -1343,7 +1596,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, cons * \returns the title of the window in UTF-8 format or "" if there is no * title. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowTitle */ @@ -1364,23 +1619,24 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); * * \param window the window to change. * \param icon an SDL_Surface structure containing the icon for the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); /** * Request that the window's position be set. * - * If, at the time of this request, the window is in a fixed-size state such - * as maximized, this request may be deferred until the window returns to a - * resizable state. + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. * * This can be used to reposition fullscreen-desktop windows onto a different - * display, however, exclusive fullscreen windows are locked to a specific - * display and can only be repositioned programmatically via + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via * SDL_SetWindowFullscreenMode(). * * On some windowing systems this request is asynchronous and the new @@ -1401,15 +1657,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_S * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * `SDL_WINDOWPOS_UNDEFINED`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); /** * Get the position of a window. @@ -1425,24 +1683,25 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, i * NULL. * \param y a pointer filled in with the y position of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowPosition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); /** * Request that the size of a window's client area be set. * - * If, at the time of this request, the window in a fixed-size state, such as - * maximized or fullscreen, the request will be deferred until the window - * exits this state and becomes resizable again. + * If the window is in a fullscreen or maximized state, this request has no + * effect. * - * To change the fullscreen mode of a window, use - * SDL_SetWindowFullscreenMode() + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). * * On some windowing systems, this request is asynchronous and the new window * size may not have have been applied immediately upon the return of this @@ -1459,16 +1718,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, i * \param window the window to change. * \param w the width of the window, must be > 0. * \param h the height of the window, must be > 0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); /** * Get the size of a window's client area. @@ -1480,16 +1741,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w * \param window the window to query the width and height from. * \param w a pointer filled in with the width of the window, may be NULL. * \param h a pointer filled in with the height of the window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize * \sa SDL_GetWindowSizeInPixels * \sa SDL_SetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); /** * Get the safe area for this window. @@ -1497,19 +1760,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int * * Some devices have portions of the screen which are partially obscured or * not interactive, possibly due to on-screen controls, curved edges, camera * notches, TV overscan, etc. This function provides the area of the window - * which is safe to have interactible content. You should continue rendering + * which is safe to have interactable content. You should continue rendering * into the rest of the window, but it should not contain visually important * or interactible content. * * \param window the window to query. * \param rect a pointer filled in with the client area that is safe for * interactive content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); /** * Request that the aspect ratio of a window's client area be set. @@ -1540,15 +1805,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, S * limit. * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); /** * Get the size of a window's client area. @@ -1558,19 +1825,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window * window, may be NULL. * \param max_aspect a pointer filled in with the maximum aspect ratio of the * window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowAspectRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); /** * Get the size of a window's borders (decorations) around the client area. * - * Note: If this function fails (returns -1), the size values will be + * Note: If this function fails (returns false), the size values will be * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the * window in question was borderless. * @@ -1580,7 +1849,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * window has been presented and composited, so that the window system has a * chance to decorate the window and provide the border dimensions to SDL. * - * This function also returns -1 if getting the information is not supported. + * This function also returns false if getting the information is not + * supported. * * \param window the window to query the size values of the border * (decorations) from. @@ -1592,14 +1862,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; * NULL is permitted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); /** * Get the size of a window's client area, in pixels. @@ -1609,15 +1881,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window * NULL. * \param h a pointer to variable for storing the height in pixels, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); /** * Set the minimum size of a window's client area. @@ -1625,15 +1899,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *windo * \param window the window to change. * \param min_w the minimum width of the window, or 0 for no limit. * \param min_h the minimum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); /** * Get the minimum size of a window's client area. @@ -1643,15 +1919,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the minimum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); /** * Set the maximum size of a window's client area. @@ -1659,15 +1937,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window * \param window the window to change. * \param max_w the maximum width of the window, or 0 for no limit. * \param max_h the maximum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); /** * Get the maximum size of a window's client area. @@ -1677,15 +1957,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the maximum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); /** * Set the border state of a window. @@ -1697,15 +1979,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window * You can't change the border state of a fullscreen window. * * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bool bordered); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); /** * Set the user-resizable state of a window. @@ -1717,15 +2001,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, S * You can't change the resizable state of a fullscreen window. * * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_bool resizable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); /** * Set the window to always be above the others. @@ -1734,43 +2020,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, * will bring the window to the front and keep the window above the rest. * * \param window the window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param on_top true to set the window always on top, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL_bool on_top); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); /** * Show a window. * * \param window the window to show. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); /** * Hide a window. * * \param window the window to hide. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); /** * Request that a window be raised above other windows and gain the input @@ -1783,12 +2075,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); /** * Request that the window be made as large as possible. @@ -1811,22 +2105,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); * and Wayland window managers may vary. * * \param window the window to maximize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MinimizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); /** * Request that the window be minimized to an iconic representation. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window - * state may not have have been applied immediately upon the return of this + * state may not have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to * block until the changes have taken effect. * @@ -1835,21 +2134,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to minimize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); /** * Request that the size and position of a minimized or maximized window be * restored. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1860,16 +2164,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to restore. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_MinimizeWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); /** * Request that the window's fullscreen state be changed. @@ -1888,18 +2194,20 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); * is just a request, it can be denied by the windowing system. * * \param window the window to change. - * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed - * mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); /** * Block until any pending window state is finalized. @@ -1915,10 +2223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * * \param window the window for which to wait for the pending state to be * applied. - * \returns SDL_TRUE on success or SDL_FALSE if the operation timed out before - * the window was in the requested state. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSize * \sa SDL_SetWindowPosition @@ -1928,20 +2238,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * \sa SDL_RestoreWindow * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SyncWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); /** * Return whether the window has a surface associated with it. * * \param window the window to query. - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. + * \returns true if there is a surface associated with the window, or false + * otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); /** * Get the SDL surface associated with the window. @@ -1961,7 +2273,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyWindowSurface * \sa SDL_WindowHasSurface @@ -1985,14 +2299,16 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * * \param window the window. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) @@ -2003,14 +2319,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *windo * \param window the window to query. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetWindowSurfaceVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); /** * Copy the window surface to the screen. @@ -2021,15 +2339,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *windo * This function is equivalent to the SDL 1.2 API SDL_Flip(). * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); /** * Copy areas of the window surface to the screen. @@ -2048,29 +2368,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window) * \param rects an array of SDL_Rect structures representing areas of the * surface to copy, in pixels. * \param numrects the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); /** * Destroy the surface associated with the window. * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); /** * Set a window's keyboard grab mode. @@ -2092,16 +2416,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window * other window loses its grab in favor of the caller's window. * * \param window the window for which the keyboard grab mode should be set. - * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab keyboard, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); /** * Set a window's mouse grab mode. @@ -2109,47 +2435,60 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *windo * Mouse grab confines the mouse cursor to the window. * * \param window the window for which the mouse grab mode should be set. - * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab mouse, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * - * \sa SDL_GetWindowMouseGrab + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); /** * Get a window's keyboard grab mode. * * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \returns true if keyboard is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); /** * Get a window's mouse grab mode. * * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \returns true if mouse is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); /** * Get the window that currently has an input grab enabled. * * \returns the window if input is grabbed or NULL otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab @@ -2165,15 +2504,18 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \param window the window that will be associated with the barrier. * \param rect a rectangle area in window-relative coordinates. If NULL the * barrier for the specified window will be destroyed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); /** * Get the mouse confinement rectangle of a window. @@ -2182,9 +2524,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, * \returns a pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab */ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window); @@ -2194,18 +2540,20 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * * The parameter `opacity` will be clamped internally between 0.0f * (transparent) and 1.0f (opaque). * - * This function also returns -1 if setting the opacity isn't supported. + * This function also returns false if setting the opacity isn't supported. * * \param window the window which will be made transparent or opaque. * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowOpacity */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); /** * Get the opacity of a window. @@ -2217,43 +2565,81 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, fl * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowOpacity */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); /** - * Set the window as a modal to a parent window. + * Set the window as a child of a parent window. * - * If the window is already modal to an existing window, it will be reparented - * to the new owner. Setting the parent window to null unparents the modal - * window and removes modal status. + * If the window is already the child of an existing window, it will be + * reparented to the new owner. Setting the parent window to NULL unparents + * the window and removes child window status. * - * Setting a window as modal to a parent that is a descendent of the modal - * window results in undefined behavior. + * If a parent window is hidden or destroyed, the operation will be + * recursively applied to child windows. Child windows hidden with the parent + * that did not have their hidden status explicitly set will be restored when + * the parent is shown. * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModal() to cancel the modal status before + * attempting to change the parent. * - * \since This function is available since SDL 3.0.0. + * Popup windows cannot change parents and attempts to do so will fail. + * + * Setting a parent window that is currently the sibling or descendent of the + * child window results in undefined behavior. + * + * \param window the window that should become the child of a parent. + * \param parent the new parent window for the child window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowModal */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window, SDL_Window *parent_window); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); /** * Set whether the window may have input focus. * * \param window the window to set focusable state. - * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow - * input focus. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param focusable true to allow input focus, false to not allow input focus. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_bool focusable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); /** @@ -2272,17 +2658,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, * the client area. * \param y the y coordinate of the menu, relative to the origin (top-left) of * the client area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); /** * Possible return values from the SDL_HitTest callback. * - * \since This enum is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This enum is available since SDL 3.2.0. * * \sa SDL_HitTest */ @@ -2335,7 +2725,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * Specifying NULL for a callback disables hit-testing. Hit-testing is * disabled by default. * - * Platforms that don't support this functionality will return SDL_FALSE + * Platforms that don't support this functionality will return false * unconditionally, even if you're attempting to disable hit-testing. * * Your callback may fire at any time, and its firing does not indicate any @@ -2349,58 +2739,72 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \param window the window to set hit-testing on. * \param callback the function to call when doing a hit-test. * \param callback_data an app-defined void pointer passed to **callback**. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); /** * Set the shape of a transparent window. * * This sets the alpha channel of a transparent window and any fully * transparent areas are also transparent to mouse clicks. If you are using - * something besides the SDL render API, then you are responsible for setting - * the alpha channel of the window yourself. + * something besides the SDL render API, then you are responsible for drawing + * the alpha channel of the window to match the shape alpha channel to get + * consistent cross-platform results. * * The shape is copied inside this function, so you can free it afterwards. If * your shape surface changes, you should call SDL_SetWindowShape() again to - * update the window. + * update the window. This is an expensive operation, so should be done + * sparingly. * * The window must have been created with the SDL_WINDOW_TRANSPARENT flag. * * \param window the window. * \param shape the surface representing the shape of the window, or NULL to * remove any current shape. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); /** * Request a window to demand attention from the user. * * \param window the window to be flashed. * \param operation the operation to perform. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); /** * Destroy a window. * - * Any popups or modal windows owned by the window will be recursively - * destroyed as well. + * Any child windows owned by the window will be recursively destroyed as + * well. + * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. * * \param window the window to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindow @@ -2416,28 +2820,31 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. + * \returns true if the screensaver is enabled, false if it is disabled. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenSaverEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); /** * Allow the screen to be blanked by a screen saver. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); /** * Prevent the screen from being blanked by a screen saver. @@ -2448,15 +2855,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); * The screensaver is disabled by default, but this may by changed by * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); /** @@ -2476,15 +2885,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); * * \param path the platform dependent OpenGL library name, or NULL to open the * default OpenGL library. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); /** * Get an OpenGL function by name. @@ -2531,7 +2942,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); * \returns a pointer to the named OpenGL function. The returned pointer * should be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ExtensionSupported * \sa SDL_GL_LoadLibrary @@ -2550,7 +2963,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char * \returns a pointer to the named EGL function. The returned pointer should * be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EGL_GetCurrentDisplay */ @@ -2559,7 +2974,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha /** * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_LoadLibrary */ @@ -2580,16 +2997,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * every time you need to know. * * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * \returns true if the extension is supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** * Reset all previously set OpenGL context attributes to their default values. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute @@ -2604,34 +3025,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * SDL_GL_GetAttribute() to check the values after creating the OpenGL * context, since the values obtained can differ from the requested ones. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * set. * \param value the desired value for the attribute. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * get. * \param value a pointer filled in with the current value of `attr`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value); /** * Create an OpenGL context for an OpenGL window, and make it current. @@ -2648,7 +3073,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *v * \returns the OpenGL context associated with `window` or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_DestroyContext * \sa SDL_GL_MakeCurrent @@ -2662,14 +3089,16 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * * \param window the window to associate with the context. * \param context the OpenGL context to associate with the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); /** * Get the currently active OpenGL window. @@ -2677,7 +3106,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_ * \returns the currently active OpenGL window on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); @@ -2687,7 +3118,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); * \returns the currently active OpenGL context or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_MakeCurrent */ @@ -2699,7 +3132,9 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * \returns the currently active EGL display or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); @@ -2709,7 +3144,9 @@ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); * \returns the currently active EGL config or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); @@ -2720,7 +3157,9 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); * \returns the EGLSurface pointer associated with the window, or NULL on * failure. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); @@ -2728,27 +3167,25 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * Sets the callbacks for defining custom EGLAttrib arrays for EGL * initialization. * - * Each callback should return a pointer to an EGL attribute array terminated - * with EGL_NONE. Callbacks may return NULL pointers to signal an error, which - * will cause the SDL_CreateWindow process to fail gracefully. - * - * The arrays returned by each callback will be appended to the existing - * attribute arrays defined by SDL. + * Callbacks that aren't needed can be set to NULL. * * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. * * \param platformAttribCallback callback for attributes to pass to - * eglGetPlatformDisplay. + * eglGetPlatformDisplay. May be NULL. * \param surfaceAttribCallback callback for attributes to pass to - * eglCreateSurface. + * eglCreateSurface. May be NULL. * \param contextAttribCallback callback for attributes to pass to - * eglCreateContext. + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, - SDL_EGLIntArrayCallback surfaceAttribCallback, - SDL_EGLIntArrayCallback contextAttribCallback); + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); /** * Set the swap interval for the current OpenGL context. @@ -2758,7 +3195,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * the vertical retrace for a given frame, it swaps buffers immediately, which * might be less jarring for the user during occasional framerate drops. If an * application requests adaptive vsync and the system does not support it, - * this function will fail and return SDL_FALSE. In such a case, you should + * this function will fail and return false. In such a case, you should * probably retry the call with 1 for the interval. * * Adaptive vsync is implemented for some glX drivers with @@ -2770,14 +3207,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * * \param interval 0 for immediate updates, 1 for updates synchronized with * the vertical retrace, -1 for adaptive vsync. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); /** * Get the swap interval for the current OpenGL context. @@ -2789,14 +3228,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); * synchronization, 1 if the buffer swap is synchronized with * the vertical retrace, and -1 if late swaps happen * immediately instead of waiting for the next retrace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_SetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); /** * Update a window with OpenGL rendering. @@ -2809,25 +3250,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); * extra. * * \param window the window to change. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); /** * Delete an OpenGL context. * * \param context the OpenGL context to be deleted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); /* @} *//* OpenGL support functions */ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h index c31d33c..5a48756 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h @@ -23,11 +23,25 @@ * # CategoryVulkan * * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. */ #ifndef SDL_vulkan_h_ #define SDL_vulkan_h_ +#include #include #include @@ -55,6 +69,10 @@ VK_DEFINE_HANDLE(VkPhysicalDevice) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) struct VkAllocationCallbacks; +/* Make sure to undef to avoid issues in case of later vulkan include */ +#undef VK_DEFINE_HANDLE +#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE + #endif /* !NO_SDL_VULKAN_TYPEDEFS */ /** @@ -69,6 +87,13 @@ struct VkAllocationCallbacks; * creating any Vulkan windows. If no Vulkan loader library is loaded, the * default library will be loaded upon creation of the first Vulkan window. * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * * It is fairly common for Vulkan applications to link with libvulkan instead * of explicitly loading it at run time. This will work with SDL provided the * application links to a dynamic library and both it and SDL use the same @@ -95,15 +120,17 @@ struct VkAllocationCallbacks; * library version. * * \param path the platform dependent Vulkan loader library name or NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); /** * Get the address of the `vkGetInstanceProcAddr` function. @@ -122,14 +149,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); /** * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_LoadLibrary */ @@ -153,7 +193,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * \returns an array of extension name strings on success, NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_CreateSurface */ @@ -175,15 +215,15 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension * allocator that creates the surface. Can be NULL. * \param surface a pointer to a VkSurfaceKHR handle to output the newly * created surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_DestroySurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, const struct VkAllocationCallbacks *allocator, VkSurfaceKHR* surface); @@ -206,7 +246,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window * \param allocator a VkAllocationCallbacks struct, which lets the app set the * allocator that destroys the surface. Can be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_CreateSurface @@ -226,14 +266,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, * \param physicalDevice a valid Vulkan physical device handle. * \param queueFamilyIndex a valid queue family index for the given physical * device. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error - * occurred. + * \returns true if supported, false if unsupported or an error occurred. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/INSTALL.md b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/INSTALL.md new file mode 100644 index 0000000..97e4ab6 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/INSTALL.md @@ -0,0 +1,41 @@ + +# Using this package + +This package contains SDL built for Xcode. + +To use this package in Xcode, drag `SDL3.framework` into your project. + +# Documentation + +An API reference, tutorials, and additional documentation is available at: + +https://wiki.libsdl.org/SDL3 + +# Example code + +There are simple example programs available at: + +https://examples.libsdl.org/SDL3 + +# Discussions + +## Discord + +You can join the official Discord server at: + +https://discord.com/invite/BwpFGBWsv8 + +## Forums/mailing lists + +You can join SDL development discussions at: + +https://discourse.libsdl.org/ + +Once you sign up, you can use the forum through the website or as a mailing list from your email client. + +## Announcement list + +You can sign up for the low traffic announcement list at: + +https://www.libsdl.org/mailing-list.php + diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Info.plist b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Info.plist index 2948e7e..6f47d98 100644 Binary files a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Info.plist and b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/Info.plist differ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/License.txt b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/License.txt index 42f3736..23abb73 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/License.txt +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/License.txt @@ -1,6 +1,4 @@ - -Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -17,3 +15,4 @@ freely, subject to the following restrictions: 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. + diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/README.md b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/README.md new file mode 100644 index 0000000..68b0923 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/README.md @@ -0,0 +1,17 @@ + +Simple DirectMedia Layer (SDL for short) is a cross-platform library +designed to make it easy to write multi-media software, such as games +and emulators. + +You can find the latest release and additional information at: +https://www.libsdl.org/ + +Installation instructions and a quick introduction is available in +[INSTALL.md](INSTALL.md) + +This library is distributed under the terms of the zlib license, +available in [LICENSE.txt](LICENSE.txt). + +Enjoy! + +Sam Lantinga (slouken@libsdl.org) diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/ReadMe.txt b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/ReadMe.txt deleted file mode 100644 index 6ea9347..0000000 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/ReadMe.txt +++ /dev/null @@ -1,44 +0,0 @@ -The Simple DirectMedia Layer (SDL for short) is a cross-platform -library designed to make it easy to write multi-media software, -such as games and emulators. - -The Simple DirectMedia Layer library source code is available from: -http://www.libsdl.org/ - -This library is distributed under the terms of the zlib license: -http://zlib.net/zlib_license.html - - -This packages contains the SDL framework for macOS. -Conforming with Apple guidelines, this framework -contains both the SDL runtime component and development header files. - - -To Install: -Copy "SDL3.xcframework" and "share" to /Library/Frameworks - -You may alternatively install it in /Library/Frameworks -if your access privileges are not high enough. - - -Use in CMake projects: -SDL3.xcframework can be used in CMake projects using the following pattern: -```cmake -find_package(SDL3 REQUIRED COMPONENTS SDL3) -add_executable(my_game ${MY_SOURCES}) -target_link_libraries(my_game PRIVATE SDL3::SDL3) -``` -If SDL3.framework is installed in a non-standard location, -please refer to the following link for ways to configure CMake: -https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure - - -Additional References: - - - Screencast tutorials for getting started with OpenSceneGraph/macOS are - available at: - http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips - Though these are OpenSceneGraph centric, the same exact concepts apply to - SDL, thus the videos are recommended for everybody getting started with - developing on macOS. (You can skim over the PlugIns stuff since SDL - doesn't have any PlugIns to worry about.) diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/SDL3 b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/SDL3 index 7b3915c..73f45aa 100755 Binary files a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/SDL3 and b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/SDL3 differ diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/_CodeSignature/CodeResources b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/_CodeSignature/CodeResources new file mode 100644 index 0000000..626ca39 --- /dev/null +++ b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/_CodeSignature/CodeResources @@ -0,0 +1,982 @@ + + + + + files + + CMake/SDL3Config.cmake + + wVPzCDAGpS2036XQsVLmiAOr8Bc= + + CMake/SDL3ConfigVersion.cmake + + gQ+LV+T54JMbmVqczZwWryOwVns= + + Headers/SDL.h + + lZ3h7l/TqUrTiXHgV15X4SmQdlg= + + Headers/SDL_assert.h + + FCAIhbQEN4FmvTlBQOOPjycjnzo= + + Headers/SDL_asyncio.h + + fGXNFcOElD6IRbX9GcJubLmoorU= + + Headers/SDL_atomic.h + + ZSetO9pGvnFdg6kNoQWBa42rYug= + + Headers/SDL_audio.h + + 4mdiUNQEXHRPqAT1Tyq7aFbrCz4= + + Headers/SDL_begin_code.h + + wsAzfk5ARMtwSG4xPvzg5m3Jz8U= + + Headers/SDL_bits.h + + 9cqOFvZxXmGK7a5xO8Lz50q6zok= + + Headers/SDL_blendmode.h + + usmRnfDgT4dxC8NUBkBLHOFce94= + + Headers/SDL_camera.h + + zHEfe8mk7gUo10V9SZo8ehQDUlY= + + Headers/SDL_clipboard.h + + UREK6p3Z6taOQm4qRmug/UrLLX8= + + Headers/SDL_close_code.h + + 1vBg1G1kDxz48iNCRQzRs4JdJXo= + + Headers/SDL_copying.h + + qgiizcHDSADGW6sbUWVXBnHDWIM= + + Headers/SDL_cpuinfo.h + + rjGkZeoG408swy+z8MRwRTXE4/A= + + Headers/SDL_dialog.h + + wRwxojHRWHS7ZY+00Ugcp+ulhVc= + + Headers/SDL_egl.h + + 2TRm4qSC+lwUqk357LIp+9RA5D0= + + Headers/SDL_endian.h + + zuQm4k5QRLG+8gYrpjTaHyKdwJo= + + Headers/SDL_error.h + + 2qWxaJQ1wp4at9K8sk+FAfpf0ig= + + Headers/SDL_events.h + + srOwCYOhw2wJ3y4TDfHmDSyCFwA= + + Headers/SDL_filesystem.h + + x2Bf0NH1HhevHFcwIIhsi1nsUlk= + + Headers/SDL_gamepad.h + + GD829JbTWBtzqqDEb8K+Kak1alU= + + Headers/SDL_gpu.h + + VUeK6nT8fg94fv2ahh3v/H6bFv0= + + Headers/SDL_guid.h + + PbhQca/PTObFyBpF0YADyZ4UxgU= + + Headers/SDL_haptic.h + + cnzDmGxX9Q613k0BUk0+kxDB/mY= + + Headers/SDL_hidapi.h + + s2YTW3pfACVyMAnkvHvbUGwbrAo= + + Headers/SDL_hints.h + + AEwxf+T99FHEv/c3SLJX3G9ZAkc= + + Headers/SDL_init.h + + 1cF9UGNdMfWCaGTFPnDilOcmbdY= + + Headers/SDL_intrin.h + + j14ekg6zAs7gojHrq8YuNsg5ftU= + + Headers/SDL_iostream.h + + INQzKo+TXazvwu2uSIXTk74A4Ms= + + Headers/SDL_joystick.h + + Dj3PmhA77DmQhaaO7TtlFVfr8Fk= + + Headers/SDL_keyboard.h + + TA2CXW0WZtojbbbD8QO5YbCtYk0= + + Headers/SDL_keycode.h + + Vep2hlXhJj2m5WJUv3YSjgwZJig= + + Headers/SDL_loadso.h + + 5kT/8rtuphyE7R7qRnWTSM3vZD8= + + Headers/SDL_locale.h + + wdVGs4oraONMu+OI1Vq89eCwgRI= + + Headers/SDL_log.h + + fchtNGMinx43j8vDGByzEG8Ug5o= + + Headers/SDL_main.h + + 5RmWvYVo9aeKVojTkH6+BW51UFQ= + + Headers/SDL_main_impl.h + + B5urjdx8niHPF6lzVXVl0e513EM= + + Headers/SDL_messagebox.h + + eLiKcRb2KqDF+NiOCLTypsmVW9c= + + Headers/SDL_metal.h + + JQbRAPxnIekwgyOzk9jNdyTrw5g= + + Headers/SDL_misc.h + + o0Zdf1k3zVEwjCK20nnKd0mE3Tk= + + Headers/SDL_mouse.h + + 5LuKu9JO0epHU72XAQi6XzeITWw= + + Headers/SDL_mutex.h + + zC93pUcPmlFIS9L8r4ciCvJm0mk= + + Headers/SDL_oldnames.h + + LVEh0rWKvPoz0Olpe7Opq43B+/Q= + + Headers/SDL_opengl.h + + nBXVdw/GJ7GDEMLjNVChtFKnnhc= + + Headers/SDL_opengl_glext.h + + TvPj1ofjtpSE6KgrLAh6PnGyZNQ= + + Headers/SDL_opengles.h + + GVQefc+XmHojZPonePHo3DmwzMw= + + Headers/SDL_opengles2.h + + y2MDVf0VqmkxR9HtNdwVas9bsig= + + Headers/SDL_opengles2_gl2.h + + GbD4M9ZIR9sxgLX4G8T/ojLVQJk= + + Headers/SDL_opengles2_gl2ext.h + + frTvd+EfShO/uonAvnnsnPkqc80= + + Headers/SDL_opengles2_gl2platform.h + + JO1DB28zz7TCz/P5YCSvV1PaqWg= + + Headers/SDL_opengles2_khrplatform.h + + mBjqEs+5bGC9u1ED2M93VNzONPQ= + + Headers/SDL_pen.h + + EXvVo7r3v4Js0CLNoAx2CfU2yFw= + + Headers/SDL_pixels.h + + sAQtWWQrbFCZTpncKsMKtnFHS1k= + + Headers/SDL_platform.h + + O0WfapqV4/M3w8tAMcj2VbsPg5M= + + Headers/SDL_platform_defines.h + + 6daGsbgvToo48b6YvBOq9M9sc3c= + + Headers/SDL_power.h + + JjIeT6uo0ADVc48kia7YbS4w6/s= + + Headers/SDL_process.h + + kekhaSL6DFc1U1O4u9PvL3gg4aw= + + Headers/SDL_properties.h + + gb6Lko32APlCWI0MC2wu4I/SQB4= + + Headers/SDL_rect.h + + y1wXNIYEgFi/LZPZLJi3Nh/6tso= + + Headers/SDL_render.h + + QzDPmDedVEINEMr8F1kzJJI9jyA= + + Headers/SDL_revision.h + + aoq5eTEZpac8JzGqebvXrvJ508w= + + Headers/SDL_scancode.h + + NCaX6yHdGwkjQ+1XlCxEpOE6KJo= + + Headers/SDL_sensor.h + + RwfqWMNjZi8O6c/e7f+l6jrWWtU= + + Headers/SDL_stdinc.h + + p5U44ukHJeOXMWHOrkm307yjChQ= + + Headers/SDL_storage.h + + KXFZhty0OaDdpkyS4U2oixZAfss= + + Headers/SDL_surface.h + + AISVaeDCftEr8gDdHW1m7ve+w5k= + + Headers/SDL_system.h + + qqeS48QOHWmApVD4vlK6r0esuqM= + + Headers/SDL_thread.h + + zzmAf2qJ9VWWB9mcS42yX6E+B0k= + + Headers/SDL_time.h + + 8B2GEH3aRj2suI7hviE/di1h4Cw= + + Headers/SDL_timer.h + + Dw3rK6vs8TgCHBqN7xNPdWp1ea4= + + Headers/SDL_touch.h + + D8Tmyow63hNMy9jEvRnaAaO1FrQ= + + Headers/SDL_tray.h + + vALAlZwywLFvWYtZOh8/39bZGtU= + + Headers/SDL_version.h + + kVdgSafPFSJe8BpriVdZkRe/57s= + + Headers/SDL_video.h + + irhtLqDbGK/7KCNTI2B3h3FCMps= + + Headers/SDL_vulkan.h + + MCL+LabbSXzNtmH4coS9Ea+8s9M= + + INSTALL.md + + fyUlqOEcE7zuLv8JGb0kUDRY4lc= + + Info.plist + + 9iYK+d1JjPXqruY35xg5NosCCU8= + + LICENSE.txt + + MV/H0zYdw5DZw6QWBIZwa65FY04= + + README.md + + ED8RfQwxZj7wFttxnetM9Q6jXX4= + + default.metallib + + aJK9hTQAkwuTq+nvDqxeToCP0m0= + + + files2 + + CMake/SDL3Config.cmake + + hash2 + + 0X7VyiYqUwqsTjqO580GDglfMgEgRhK7uFFUgPccqrk= + + + CMake/SDL3ConfigVersion.cmake + + hash2 + + o4od03lMXeFmSf7XQVrg+cMoEnzDAA0bJIE6oslEQe0= + + + Headers/SDL.h + + hash2 + + Cvdi4gF6iiTrPFFXBN8WVYzKuQogVno9ER2HjYHLD78= + + + Headers/SDL_assert.h + + hash2 + + GUKvmslH9JBDeZwVHFV+dJ7uRugCENjA2fi0NvkXP6o= + + + Headers/SDL_asyncio.h + + hash2 + + 6eQHTxs1vaIfPh2XJZ8Dxl4txtqcXyGNKYkEdckwbaY= + + + Headers/SDL_atomic.h + + hash2 + + PgrpKCw7TgKe8KHwM5rZiv5NmW9QXjmnbtbdlhWZpjk= + + + Headers/SDL_audio.h + + hash2 + + VvBp9u2lRJVv9qyun1cSYcFrEcFfxL8Sug+lFgPr6zU= + + + Headers/SDL_begin_code.h + + hash2 + + fxk2E7HjevknSqJuM6gdTVdk729oKqu6dGiIKlngKOI= + + + Headers/SDL_bits.h + + hash2 + + H88Gt0fGZ+U7ts+dAX1avFoprYg8Be7fz7AhxXG2FZI= + + + Headers/SDL_blendmode.h + + hash2 + + hAasxDnDlaxJ6necLTgqEtqXgyUxOY9o6DttaAzAP8U= + + + Headers/SDL_camera.h + + hash2 + + QVRcv5xfFyaG/Co9MnzrUy3C0NEo16s3zIbl6UwkUuw= + + + Headers/SDL_clipboard.h + + hash2 + + nm+rMDYWWqbnVnJ9sg8fShfLgFD1nALxB8KsBdNTuRU= + + + Headers/SDL_close_code.h + + hash2 + + zjynPn/VKTMQ/RVWksWLXoLlFvGoJn+E0K9XLIOY4+k= + + + Headers/SDL_copying.h + + hash2 + + ZENtUHjWdC8RyLCs+LyHI30V2jZxbrJVKYaotFxBmWc= + + + Headers/SDL_cpuinfo.h + + hash2 + + wDNjucbJP3UbWyU9Y2IIuqnWZYxpJoArNRaXNrlvGu8= + + + Headers/SDL_dialog.h + + hash2 + + uSXny36TRgIvEu9/b3g7AVOwfCSVETRcNiyye6ptSMU= + + + Headers/SDL_egl.h + + hash2 + + ZI1DHIxRuv6skDbbF8PuX96mtre4/huG2LdUFjDXzds= + + + Headers/SDL_endian.h + + hash2 + + 37jA4lsA1YiTsAWGk5vvZj/H/tf4+yDoCf7vcJa9Ew0= + + + Headers/SDL_error.h + + hash2 + + fSlLo+mUuJpCvGNG5+Wb/4L7zi0FD3zbGJ2PRfMXlfI= + + + Headers/SDL_events.h + + hash2 + + 6B7T1/y4oKgsbog2B2QL6UZ4vv4UnNRnk1Lhi807z3Q= + + + Headers/SDL_filesystem.h + + hash2 + + bR6AD/KyDeLQQW98aBfdbxGzufw7+4C+WDTjBpRmy9I= + + + Headers/SDL_gamepad.h + + hash2 + + TGeZjBGUlOjcgkIzBwKK2YpN508+deGN8RMmwTx3hRI= + + + Headers/SDL_gpu.h + + hash2 + + 2tUSvuo5Ev+GaOaDzcaLUYmJT5z1/Qxi4rfF/ejz4IE= + + + Headers/SDL_guid.h + + hash2 + + lYJzCv4bmAURGxZ8Yv7DmXsFLoA0VShvmZPDA8M6z7U= + + + Headers/SDL_haptic.h + + hash2 + + qLujijGSmObisRAEHA+3sUS2/sicBu5CiFRULbc9tw8= + + + Headers/SDL_hidapi.h + + hash2 + + BS/UNHgeoUgUP0ZE7Wr1ElicSkMtMcXZRy0vOU1OsWs= + + + Headers/SDL_hints.h + + hash2 + + zZW0/QZMSL38EomWyrpmd/wrv5wgUFUbQL1T+Liy/fE= + + + Headers/SDL_init.h + + hash2 + + X1qr3eJdWv9RNxQK9U/hAHM/7fyvLI8fbHE4pQqdSIo= + + + Headers/SDL_intrin.h + + hash2 + + YlLnI56pNm7vQnEwH6oDfki+eqMkQ0FPStKovXGGxmY= + + + Headers/SDL_iostream.h + + hash2 + + 2wZxMiUAboSqkmYgGObh9demGS4uXGetGIOddzOoBxU= + + + Headers/SDL_joystick.h + + hash2 + + r0aPy8paE7O55PiB3ku4l++dZITgfb2mBLYkZXPzg7U= + + + Headers/SDL_keyboard.h + + hash2 + + QMAEiiN+f9SUaPFtczb4DFrl44iMPNHXveQxWfYGgq0= + + + Headers/SDL_keycode.h + + hash2 + + CGHx7BS7/S7d8qMTXN1PVcyq+oGig+V0AjbvTRDo5wA= + + + Headers/SDL_loadso.h + + hash2 + + LucDpNvlT+qEmAE0wm0hy4fDDfS3r9+ho8xspu9k4J4= + + + Headers/SDL_locale.h + + hash2 + + s0UA/AyUaFIR/UxuFbAnLzul37UAYEB8OQHGyemDmFs= + + + Headers/SDL_log.h + + hash2 + + 0ypVf/5dM6mKA3D2BbkFRVoQaIuqUEDMEu1d5a59kak= + + + Headers/SDL_main.h + + hash2 + + dExUeHgHxUtHVpvJKFF6GLiPaRKS2UZ84V8JwgNYn/c= + + + Headers/SDL_main_impl.h + + hash2 + + nLJhKmOzMf/3oNn8MHvp28Ph8hx7CuZOgYGvyxa0Fg8= + + + Headers/SDL_messagebox.h + + hash2 + + f9JqShergM7ApYxHQJp0rMwnRA2TW3m1COEQmJgrwMg= + + + Headers/SDL_metal.h + + hash2 + + 7Fs5+iU7qLHNh8XkDvbeNtwypYjyDVB4sBEoASSwgkA= + + + Headers/SDL_misc.h + + hash2 + + zlOAZjhmbs3kUq4/i86aZTyFOf54uMb9lYW9SIjsk+A= + + + Headers/SDL_mouse.h + + hash2 + + YjZ7PHxJHE7eO4DD5IZ1dJmRmr1AK94SCg+xivpEFqw= + + + Headers/SDL_mutex.h + + hash2 + + K0mA/DdrF5+fAYkt6vZ5qNonce+zAecF0f+2ay6eciU= + + + Headers/SDL_oldnames.h + + hash2 + + pGGsTEnGS1qN38nfrQooK1X/CM4p6EhYwHuSrUCuZCE= + + + Headers/SDL_opengl.h + + hash2 + + LqWxBvkb9UooP3YdPv2hhaUV7Z1hcCrHNXJ0kg5pIC4= + + + Headers/SDL_opengl_glext.h + + hash2 + + 2IXkrwf1MIPKwa6QphzLOTF5R+5z5SFlBvsl9q5QMyQ= + + + Headers/SDL_opengles.h + + hash2 + + q8cYr3RT0WnR58ff37XZOaJQUZvuAt99QuDWplt+DIU= + + + Headers/SDL_opengles2.h + + hash2 + + 0ENhHFweBuRmpiO4jR7kmHRilduMwfFfGHLBl0IEUhc= + + + Headers/SDL_opengles2_gl2.h + + hash2 + + 1uxEsdc/OvzjogrGl223+z2sZWxRkPC1Y+TOkNeaFao= + + + Headers/SDL_opengles2_gl2ext.h + + hash2 + + T8WwA03N6cElki4+cNAUiaazNQdoVu5mApThpjBaNxk= + + + Headers/SDL_opengles2_gl2platform.h + + hash2 + + R3m+mZrNGQRFgjjwnIaYO3lgrEDmEuBdstuX22FfHg8= + + + Headers/SDL_opengles2_khrplatform.h + + hash2 + + ex4Bqqetj2/DS1x733nr9RibsJ4sTS55/F01BiPRHoM= + + + Headers/SDL_pen.h + + hash2 + + kMVe4rIilC0D2bCBXaQuTbyJcfYuFB6NF2zY0GMHZSc= + + + Headers/SDL_pixels.h + + hash2 + + LNF1mr8/q/ySYmhjN3BTRHUt8uoP0y2eaqGUSd01l1Q= + + + Headers/SDL_platform.h + + hash2 + + rJzzCb3cDnVV++HUJYN7rROraIegCilBvo1PzfSzERo= + + + Headers/SDL_platform_defines.h + + hash2 + + 1gY0D+xDbD99hyMrgCSftn/D98qE6Yzn384cCqguVQU= + + + Headers/SDL_power.h + + hash2 + + d9umbBzotQlz1MRiww4CcbV9plDfGYfg3LaoLI3Scro= + + + Headers/SDL_process.h + + hash2 + + Z6C8A6FVpoIFvmXDeVS57eD4WN5vSQcIcaKjUB9vmAQ= + + + Headers/SDL_properties.h + + hash2 + + FMSMnEfaIzvmuD/o5CBL6rhd6pXGuhrkjmSQ1F6mTt8= + + + Headers/SDL_rect.h + + hash2 + + dlouxLVTArPG98yxRQqcSEB/uMsozkfdcpTtRIU4Ojs= + + + Headers/SDL_render.h + + hash2 + + TTzckAGMIupcnJuLd1+U5SiZgRfytR/bTs1yRoWV56E= + + + Headers/SDL_revision.h + + hash2 + + kzj2kc5o0jOr8L5Dp5XLTtDRK+/WBebI7bVi3oVcjqA= + + + Headers/SDL_scancode.h + + hash2 + + Mz+cUcJxVYNH1PgH1HQ1lms9b/w6rFkgovMaKX/MFfs= + + + Headers/SDL_sensor.h + + hash2 + + hkGEpyGOUWQhmMkuMasy86uqDchGDP1O8OLMic0d45M= + + + Headers/SDL_stdinc.h + + hash2 + + 1lQYyQZpVGCCIEVg1wB60YfE/4v9zVXcNgevbNJRLPs= + + + Headers/SDL_storage.h + + hash2 + + oxSWVHUbbqMKvx1QBuV39bmyH+VFJj/wE9axnBIA0t4= + + + Headers/SDL_surface.h + + hash2 + + Js/qrm2ltYV2bTT/AUSXIgbmPDb21TuhNGd+j91G6Bs= + + + Headers/SDL_system.h + + hash2 + + j+vc/6qa/tWwnNVuxFtl/+ZasjDpFiKIj/SWs9WvmoA= + + + Headers/SDL_thread.h + + hash2 + + zNaMperhXe4mP0ZQ9LMd/CewmlKkw4xTJpKu7FlubnA= + + + Headers/SDL_time.h + + hash2 + + 2uMjroK2pJQqTpQYR37U8oTurEuBWWavK4ypNIQrjiI= + + + Headers/SDL_timer.h + + hash2 + + 5hkyTURkMquzzC9SGKwImyNFwA5FTsUrX8cj8Tfkvzw= + + + Headers/SDL_touch.h + + hash2 + + IkjbfrMdhQ3G93hAl6yyUMG6/mUIs+kVUEeP//1GUmE= + + + Headers/SDL_tray.h + + hash2 + + KA3SCxpjMIcM5EeEHC6F3o9/5CFr8kAVvsd8Ra+pUms= + + + Headers/SDL_version.h + + hash2 + + 227opDjmxbL8YKwXKqGjwoVvSgAOjqD/x5Gz0fDdC7A= + + + Headers/SDL_video.h + + hash2 + + Yb5Cg96tQZZ0ErDNn2e33TSvsXYbcUYgShi8M3jkjHk= + + + Headers/SDL_vulkan.h + + hash2 + + yHTw0Wf4WcYGEJtGQKPo0qMY51hlnmVhLCebseJiLwg= + + + INSTALL.md + + hash2 + + cfN7quEEdthPBp+Ef9Fnvue8PyOFBgmdeNoftdFDzR8= + + + LICENSE.txt + + hash2 + + l/NbMCs2FoDsHokeldLVIJe7lav/NhQ0kW2Z3BMF8Sc= + + + README.md + + hash2 + + QboZO+koFZBptSlJqxoTwskW+z99BRNKDR6cxw1Mfrg= + + + default.metallib + + hash2 + + 5zQ2W5RhvGbUmNk9QzcZii90676kkTLdiAd2eAHYNsE= + + + + rules + + ^.* + + ^.*\.lproj/ + + optional + + weight + 1000 + + ^.*\.lproj/locversion.plist$ + + omit + + weight + 1100 + + ^Base\.lproj/ + + weight + 1010 + + ^version.plist$ + + + rules2 + + .*\.dSYM($|/) + + weight + 11 + + ^(.*/)?\.DS_Store$ + + omit + + weight + 2000 + + ^.* + + ^.*\.lproj/ + + optional + + weight + 1000 + + ^.*\.lproj/locversion.plist$ + + omit + + weight + 1100 + + ^Base\.lproj/ + + weight + 1010 + + ^Info\.plist$ + + omit + + weight + 20 + + ^PkgInfo$ + + omit + + weight + 20 + + ^embedded\.provisionprofile$ + + weight + 20 + + ^version\.plist$ + + weight + 20 + + + + diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/compile_shaders.sh b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/compile_shaders.sh deleted file mode 100755 index ef5e744..0000000 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/compile_shaders.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/bin/bash - -set -x -set -e -cd `dirname "$0"` - -shadernames=(FullscreenVert BlitFrom2D BlitFrom2DArray BlitFrom3D BlitFromCube) - -generate_shaders() -{ - fileplatform=$1 - compileplatform=$2 - sdkplatform=$3 - minversion=$4 - - for shadername in "${shadernames[@]}"; do - xcrun -sdk $sdkplatform metal -c -std=$compileplatform-metal1.1 -m$sdkplatform-version-min=$minversion -Wall -O3 -D COMPILE_$shadername -o ./$shadername.air ./Metal_Blit.metal || exit $? - xcrun -sdk $sdkplatform metallib -o $shadername.metallib $shadername.air || exit $? - xxd -i $shadername.metallib | perl -w -p -e 's/\Aunsigned /const unsigned /;' >./${shadername}_$fileplatform.h - rm -f $shadername.air $shadername.metallib - done -} - -generate_shaders macos macos macosx 10.11 -generate_shaders ios ios iphoneos 8.0 -generate_shaders iphonesimulator ios iphonesimulator 8.0 -generate_shaders tvos ios appletvos 9.0 -generate_shaders tvsimulator ios appletvsimulator 9.0 - -# Bundle together one mega-header -catShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - cat ${shadername}_$target.h >> Metal_Blit.h - done -} - -rm -f Metal_Blit.h -echo "#if defined(SDL_PLATFORM_IOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders iphonesimulator - echo "#else" >> Metal_Blit.h - catShaders ios - echo "#endif" >> Metal_Blit.h -echo "#elif defined(SDL_PLATFORM_TVOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders tvsimulator - echo "#else" >> Metal_Blit.h - catShaders tvos - echo "#endif" >> Metal_Blit.h -echo "#else" >> Metal_Blit.h - catShaders macos -echo "#endif" >> Metal_Blit.h - -# Clean up -cleanupShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - rm -f ${shadername}_$target.h - done -} -cleanupShaders iphonesimulator -cleanupShaders ios -cleanupShaders tvsimulator -cleanupShaders tvos -cleanupShaders macos \ No newline at end of file diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/default.metallib b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/default.metallib index 3c378dc..8e524d3 100644 Binary files a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/default.metallib and b/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/default.metallib differ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL.h index c963394..861c404 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -20,9 +20,12 @@ */ /** - * \file SDL.h + * Main include header for the SDL library, version 3.2.0 * - * Main include header for the SDL library, version 3.1.2 + * It is almost always best to include just this one header instead of + * picking out individual headers included here. There are exceptions to + * this rule--SDL_main.h is special and not included here--but usually + * letting SDL.h include the kitchen sink for you is the correct approach. */ #ifndef SDL_h_ @@ -30,6 +33,7 @@ #include #include +#include #include #include #include @@ -65,6 +69,7 @@ #include #include #include +#include #include #include #include @@ -76,6 +81,7 @@ #include #include #include +#include #include #include #include diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_assert.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_assert.h index f5f798e..09b3b47 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_assert.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_assert.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,9 +51,14 @@ * - It provides statistics and data on all failed assertions to the app. * - It allows the default assertion handler to be controlled with environment * variables, in case an automated script needs to control it. + * - It can be used as an aid to Clang's static analysis; it will treat SDL + * assertions as universally true (under the assumption that you are serious + * about the asserted claims and that your debug builds will detect when + * these claims were wrong). This can help the analyzer avoid false + * positives. * - * To use it: do a debug build and just sprinkle around tests to check your - * code! + * To use it: compile a debug build and just sprinkle around tests to check + * your code! */ #ifndef SDL_assert_h_ @@ -84,7 +89,7 @@ extern "C" { * - 3: Paranoid settings: All SDL assertion macros enabled, including * SDL_assert_paranoid. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors @@ -113,24 +118,27 @@ extern "C" { * * If the program is not running under a debugger, SDL_TriggerBreakpoint will * likely terminate the app, possibly without warning. If the current platform - * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro - * does nothing. + * isn't supported, this macro is left undefined. * - * \threadsafety It is safe to call this function from any thread. + * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner -#elif defined(_MSC_VER) +#elif 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) #include #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__)) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) @@ -147,18 +155,40 @@ extern "C" { #include #define SDL_TriggerBreakpoint() raise(SIGTRAP) #else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ #endif -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FUNCTION __FUNCTION__ + +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ # define SDL_FUNCTION __func__ #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) # define SDL_FUNCTION __FUNCTION__ #else # define SDL_FUNCTION "???" #endif + +/** + * A macro that reports the current file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FILE __FILE__ + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_LINE __LINE__ /* @@ -176,14 +206,50 @@ This also solves the problem of... disable assertions. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro for wrapping code in `do {} while (0);` without compiler warnings. + * + * Visual Studio with really aggressive warnings enabled needs this to avoid + * compiler complaints. + * + * the `do {} while (0);` trick is useful for wrapping code in a macro that + * may or may not be a single statement, to avoid various C language + * accidents. + * + * To use: + * + * ```c + * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0)); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NULL_WHILE_LOOP_CONDITION (0) + +#elif defined(_MSC_VER) /* Avoid /W4 warnings. */ /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking this condition isn't constant. And looks like an owl's face! */ -#ifdef _MSC_VER /* stupid /W4 warnings. */ #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) #else #define SDL_NULL_WHILE_LOOP_CONDITION (0) #endif +/** + * The macro used when an assertion is disabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is disabled (perhaps in a release build). + * + * The code does nothing, but wraps `condition` in a sizeof operator, which + * generates no code and has no side effects, but avoid compiler warnings + * about unused variables. + * + * \param condition the condition to assert (but not actually run here). + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -198,7 +264,7 @@ disable assertions. * condition, try to break in a debugger, kill the program, or ignore the * problem). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AssertState { @@ -216,11 +282,11 @@ typedef enum SDL_AssertState * used by the assertion handler, then added to the assertion report. This is * returned as a linked list from SDL_GetAssertionReport(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AssertData { - SDL_bool always_ignore; /**< SDL_TRUE if app should always continue when assertion is triggered. */ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ const char *condition; /**< A string of this assert's test code. */ const char *filename; /**< The source file where this assert lives. */ @@ -232,7 +298,7 @@ typedef struct SDL_AssertData /** * Never call this directly. * - * Use the SDL_assert* macros instead. + * Use the SDL_assert macros instead. * * \param data assert data structure. * \param func function name. @@ -240,29 +306,57 @@ typedef struct SDL_AssertData * \param line line number. * \returns assert state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN; -/* Define the trigger breakpoint call used in asserts */ -#ifndef SDL_AssertBreakpoint -#if defined(ANDROID) && defined(assert) -/* Define this as empty in case assert() is defined as SDL_assert */ -#define SDL_AssertBreakpoint() -#else + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The macro used when an assertion triggers a breakpoint. + * + * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint + * instead. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() -#endif + +#elif !defined(SDL_AssertBreakpoint) +# if defined(ANDROID) && defined(assert) + /* Define this as empty in case assert() is defined as SDL_assert */ +# define SDL_AssertBreakpoint() +# else +# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() +# endif #endif /* !SDL_AssertBreakpoint */ -/* the do {} while(0) avoids dangling else problems: - if (x) SDL_assert(y); else blah(); - ... without the do/while, the "else" could attach to this macro's "if". - We try to handle just the minimum we need here in a macro...the loop, - the static vars, and break points. The heavy lifting is handled in - SDL_ReportAssertion(), in SDL_assert.c. -*/ +/** + * The macro used when an assertion is enabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is enabled. + * + * The `do {} while(0)` avoids dangling else problems: + * + * ```c + * if (x) SDL_assert(y); else blah(); + * ``` + * + * ... without the do/while, the "else" could attach to this macro's "if". We + * try to handle just the minimum we need here in a macro...the loop, the + * static vars, and break points. The heavy lifting is handled in + * SDL_ReportAssertion(). + * + * \param condition the condition to assert. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ @@ -305,7 +399,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; } @@ -336,7 +432,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_release(condition) SDL_disabled_assert(condition) @@ -363,7 +461,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) @@ -389,7 +489,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * #endif /** - * An assertion test that always performed. + * An assertion test that is always performed. * * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You * almost never want to use this, as it could trigger on an end-user's system, @@ -405,7 +505,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_always(condition) SDL_enabled_assert(condition) @@ -418,7 +520,10 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. * - * \since This datatype is available since SDL 3.0.0. + * \threadsafety This callback may be called from any thread that triggers an + * assert at any time. + * + * \since This datatype is available since SDL 3.2.0. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( const SDL_AssertData *data, void *userdata); @@ -440,7 +545,9 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * fails or NULL for the default handler. * \param userdata a pointer that is passed to `handler`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -459,7 +566,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler( * \returns the default SDL_AssertionHandler that is called when an assert * triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -482,7 +591,9 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler( * was passed to SDL_SetAssertionHandler(). * \returns the SDL_AssertionHandler that is called when an assert triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAssertionHandler */ @@ -508,9 +619,15 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void ** * ``` * * \returns a list of all failed assertions or NULL if the list is empty. This - * memory should not be modified or freed by the application. + * memory should not be modified or freed by the application. This + * pointer remains valid until the next call to SDL_Quit() or + * SDL_ResetAssertionReport(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads calling + * SDL_ResetAssertionReport() simultaneously, may render the + * returned pointer invalid. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetAssertionReport */ @@ -524,7 +641,11 @@ extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); * no items. In addition, any previously-triggered assertions will be reset to * a trigger_count of zero, and their always_ignore state will be false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads triggering an + * assertion, or simultaneously calling this function may cause + * memory leaks or crashes. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionReport */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_asyncio.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_asyncio.h new file mode 100644 index 0000000..b36cb07 --- /dev/null +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/* WIKI CATEGORY: AsyncIO */ + +/** + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + */ + +#ifndef SDL_asyncio_h_ +#define SDL_asyncio_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOTaskType +{ + SDL_ASYNCIO_TASK_READ, /**< A read operation. */ + SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */ + SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */ +} SDL_AsyncIOTaskType; + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOResult +{ + SDL_ASYNCIO_COMPLETE, /**< request was completed without error */ + SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */ + SDL_ASYNCIO_CANCELED /**< request was canceled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AsyncIOOutcome +{ + SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + void *buffer; /**< buffer where data was read/written. */ + Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + void *userdata; /**< pointer provided by the app when starting the task */ +} SDL_AsyncIOOutcome; + +/** + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode); + +/** + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); + +/** + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); + +/** + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome); + +/** + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS); + +/** + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_asyncio_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_atomic.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_atomic.h index f159bcd..03e3fb1 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_atomic.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_atomic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -88,15 +88,16 @@ typedef int SDL_SpinLock; * doing. Please be careful using any sort of spinlock!*** * * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. + * \returns true if the lock succeeded, false if the lock is already held. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_UnlockSpinlock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); /** * Lock a spin lock by setting it to a non-zero value. @@ -106,7 +107,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockSpinlock * \sa SDL_UnlockSpinlock @@ -123,7 +126,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_TryLockSpinlock @@ -147,9 +152,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -166,7 +172,50 @@ extern __inline void SDL_CompilerBarrier(void); #endif /** - * Insert a memory release barrier. + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); + +/** + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Insert a memory release barrier (macro version). * * Memory barriers are designed to prevent reads and writes from being * reordered by the compiler and being seen out of order on multi-core CPUs. @@ -186,31 +235,47 @@ extern __inline void SDL_CompilerBarrier(void); * For more information on these semantics, take a look at the blog post: * http://preshing.com/20120913/acquire-and-release-semantics * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierReleaseFunction to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() /** - * Insert a memory acquire barrier. + * Insert a memory acquire barrier (macro version). * - * Please refer to SDL_MemoryBarrierReleaseFunction for the details! + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. * - * \threadsafety Obviously this function is safe to use from any thread at any + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_MemoryBarrierReleaseFunction + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -/* !!! FIXME: this should have documentation! */ -#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) +#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") #elif defined(__GNUC__) && defined(__aarch64__) @@ -225,8 +290,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); hard-coded at address 0xffff0fa0 */ typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() #else #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") @@ -276,9 +341,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * * \threadsafety This macro is safe to use from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay + #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */ #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__) @@ -303,9 +369,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * A type representing an atomic integer value. * * This can be used to manage a value that is synchronized across multiple - * CPUs without a race condition; when an app sets a value with SDL_AtomicSet - * all other threads, regardless of the CPU it is running on, will see that - * value when retrieved with SDL_AtomicGet, regardless of CPU caches, etc. + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. * * This is also useful for atomic compare-and-swap operations: a thread can * change the value as long as its current value matches expectations. When @@ -316,14 +383,14 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * this!). * * This is a struct so people don't accidentally use numeric operations on it - * directly. You have to use SDL_Atomic* functions. + * directly. You have to use SDL atomic functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - * \sa SDL_AtomicAdd + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt */ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; @@ -336,15 +403,16 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; * \param a a pointer to an SDL_AtomicInt variable to be modified. * \param oldval the old value. * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. + * \returns true if the atomic variable was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, int oldval, int newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); /** * Set an atomic variable to a value. @@ -360,11 +428,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicGet + * \sa SDL_GetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); /** * Get the value of an atomic variable. @@ -377,11 +445,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicSet + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); /** * Add to an atomic variable. @@ -397,12 +465,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef * \sa SDL_AtomicIncRef */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); #ifndef SDL_AtomicIncRef @@ -414,11 +482,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to an SDL_AtomicInt to increment. * \returns the previous value of the atomic variable. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef */ -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) #endif #ifndef SDL_AtomicDecRef @@ -429,16 +499,103 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * ***Note: If you don't know what this macro is for, you shouldn't use it!*** * * \param a a pointer to an SDL_AtomicInt to increment. - * \returns SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise. + * \returns true if the variable reached zero after decrementing, false + * otherwise. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicIncRef */ -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) #endif +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***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 oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * 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. + * \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.2.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***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. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + /** * Set a pointer to a new value if it is currently an old value. * @@ -448,17 +605,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to a pointer. * \param oldval the old pointer value. * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. + * \returns true if the pointer was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGetPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, void *oldval, void *newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); /** * Set a pointer to a value atomically. @@ -472,12 +629,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicGetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); /** * Get the value of a pointer atomically. @@ -490,12 +647,12 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicGetPointer(void **a); +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_audio.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_audio.h index b7a4b7b..9569382 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_audio.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_audio.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -33,8 +33,9 @@ * even if the data format changes on either side halfway through. * * An app opens an audio device and binds any number of audio streams to it, - * feeding more data to it as available. When the devices needs more data, it - * will pull it from all bound streams and mix them together for playback. + * feeding more data to the streams as available. When the device needs more + * data, it will pull it from all bound streams and mix them together for + * playback. * * Audio streams can also use an app-provided callback to supply data * on-demand, which maps pretty closely to the SDL2 audio model. @@ -43,6 +44,45 @@ * if you aren't reading from a file) as a basic means to load sound data into * your program. * + * ## Logical audio devices + * + * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a + * logical device ID that you can bind audio streams to. In almost all cases, + * logical devices can be used anywhere in the API that a physical device is + * normally used. However, since each device opening generates a new logical + * device, different parts of the program (say, a VoIP library, or + * text-to-speech framework, or maybe some other sort of mixer on top of SDL) + * can have their own device opens that do not interfere with each other; each + * logical device will mix its separate audio down to a single buffer, fed to + * the physical device, behind the scenes. As many logical devices as you like + * can come and go; SDL will only have to open the physical device at the OS + * level once, and will manage all the logical devices on top of it + * internally. + * + * One other benefit of logical devices: if you don't open a specific physical + * device, instead opting for the default, SDL can automatically migrate those + * logical devices to different hardware as circumstances change: a user + * plugged in headphones? The system default changed? SDL can transparently + * migrate the logical devices to the correct physical device seamlessly and + * keep playing; the app doesn't even have to know it happened if it doesn't + * want to. + * + * ## Simplified audio + * + * As a simplified model for when a single source of audio is all that's + * needed, an app can use SDL_OpenAudioDeviceStream, which is a single + * function to open an audio device, create an audio stream, bind that stream + * to the newly-opened device, and (optionally) provide a callback for + * obtaining audio data. When using this function, the primary interface is + * the SDL_AudioStream and the device handle is mostly hidden away; destroying + * a stream created through this function will also close the device, stream + * bindings cannot be changed, etc. One other quirk of this is that the device + * is started in a _paused_ state and must be explicitly resumed; this is + * partially to offer a clean migration for SDL2 apps and partially because + * the app might have to do more setup before playback begins; in the + * non-simplified form, nothing will play until a stream is bound to a device, + * so they start _unpaused_. + * * ## Channel layouts * * Audio data passing through SDL is uncompressed PCM data, interleaved. One @@ -73,7 +113,7 @@ * - 4 channels (quad) layout: FL, FR, BL, BR * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be - * BL, BR) + * SL, SR) * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR * @@ -94,7 +134,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -102,19 +141,73 @@ extern "C" { #endif -/* masks for different parts of SDL_AudioFormat. */ +/** + * Mask of bits in an SDL_AudioFormat that contains the format bit size. + * + * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BITSIZE (0xFFu) + +/** + * Mask of bits in an SDL_AudioFormat that contain the floating point flag. + * + * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_FLOAT (1u<<8) + +/** + * Mask of bits in an SDL_AudioFormat that contain the bigendian flag. + * + * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN + * instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12) + +/** + * Mask of bits in an SDL_AudioFormat that contain the signed data flag. + * + * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_SIGNED (1u<<15) -#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \ - (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) +/** + * Define an SDL_AudioFormat value. + * + * SDL does not support custom audio formats, so this macro is not of much use + * externally, but it can be illustrative as to what the various bits of an + * SDL_AudioFormat mean. + * + * For example, SDL_AUDIO_S32LE looks like this: + * + * ```c + * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32) + * ``` + * + * \param signed 1 for signed data, 0 for unsigned data. + * \param bigendian 1 for bigendian data, 0 for littleendian data. + * \param flt 1 for floating point data, 0 for integer data. + * \param size number of bits per sample. + * \returns a format value in the style of SDL_AudioFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \ + (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) /** * Audio format. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_AUDIO_BITSIZE * \sa SDL_AUDIO_BYTESIZE @@ -144,17 +237,18 @@ typedef enum SDL_AudioFormat /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ -} SDL_AudioFormat; -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_AUDIO_S16 SDL_AUDIO_S16LE -#define SDL_AUDIO_S32 SDL_AUDIO_S32LE -#define SDL_AUDIO_F32 SDL_AUDIO_F32LE -#else -#define SDL_AUDIO_S16 SDL_AUDIO_S16BE -#define SDL_AUDIO_S32 SDL_AUDIO_S32BE -#define SDL_AUDIO_F32 SDL_AUDIO_F32BE -#endif + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; /** @@ -167,7 +261,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) @@ -181,7 +275,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) @@ -195,7 +289,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) @@ -209,7 +303,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) @@ -223,7 +317,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) @@ -237,7 +331,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) @@ -251,7 +345,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) @@ -265,7 +359,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) @@ -275,7 +369,7 @@ typedef enum SDL_AudioFormat * * Zero is used to signify an invalid/null device. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_AudioDeviceID; @@ -286,7 +380,7 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu) @@ -297,14 +391,14 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu) /** * Format specifier for audio data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AudioFormat */ @@ -326,7 +420,7 @@ typedef struct SDL_AudioSpec * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) @@ -350,7 +444,7 @@ typedef struct SDL_AudioSpec * more of them, bind them to an opened audio device, and feed data to them * (or for recording, consume data from them). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -359,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream; /* Function prototypes */ -/** - * \name Driver discovery functions - * - * These functions return the list of built in audio drivers, in the - * order that they are normally initialized by default. - */ -/* @{ */ - /** * Use this function to get the number of built-in audio drivers. * @@ -384,7 +470,7 @@ typedef struct SDL_AudioStream SDL_AudioStream; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDriver */ @@ -408,12 +494,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. @@ -427,7 +512,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); @@ -453,7 +538,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioRecordingDevices @@ -482,7 +567,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioPlaybackDevices @@ -498,11 +583,10 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioPlaybackDevices * \sa SDL_GetAudioRecordingDevices - * \sa SDL_GetDefaultAudioInfo */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); @@ -532,14 +616,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI * \param spec on return, will be filled with device details. * \param sample_frames pointer to store device buffer size, in sample frames. * Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); /** * Get the current channel map of an audio device. @@ -558,7 +642,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -633,13 +717,52 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseAudioDevice * \sa SDL_GetAudioDeviceFormat */ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec); +/** + * Determine if an audio device is physical (instead of logical). + * + * An SDL_AudioDeviceID that represents physical hardware is a physical + * device; there is one for each piece of hardware that SDL can see. Logical + * devices are created by calling SDL_OpenAudioDevice or + * SDL_OpenAudioDeviceStream, and while each is associated with a physical + * device, there can be any number of logical devices on one physical device. + * + * For the most part, logical and physical IDs are interchangeable--if you try + * to open a logical device, SDL understands to assign that effort to the + * underlying physical device, etc. However, it might be useful to know if an + * arbitrary device ID is physical or logical. This function reports which. + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a physical device, false if it is logical. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid); + +/** + * Determine if an audio device is a playback device (instead of recording). + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a playback device, false if it is recording. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid); + /** * Use this function to pause audio playback on a specified device. * @@ -659,17 +782,17 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioDevice * \sa SDL_AudioDevicePaused */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to unpause audio playback on a specified device. @@ -687,17 +810,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev) * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AudioDevicePaused * \sa SDL_PauseAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to query if an audio device is paused. @@ -710,16 +833,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev * IDs will report themselves as unpaused here. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. + * \returns true if device is valid and paused, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Get the gain of an audio device. @@ -738,7 +861,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioDeviceGain */ @@ -753,8 +876,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * Audio devices default to a gain of 1.0f (no change in output). * * Physical devices may not have their gain changed, only logical devices, and - * this function will always return -1 when used on physical devices. While it - * might seem attractive to adjust several logical devices at once in this + * this function will always return false when used on physical devices. While + * it might seem attractive to adjust several logical devices at once in this * way, it would allow an app or library to interfere with another portion of * the program's otherwise-isolated devices. * @@ -767,17 +890,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \param devid the audio device on which to change gain. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDeviceGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); /** * Close a previously-opened audio device. @@ -794,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID de * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice */ @@ -819,23 +942,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * Binding a stream to a device will set its output format for playback * devices, and its input format for recording devices, so they match the * device's settings. The caller is welcome to change the other end of the - * stream's format at any time. + * stream's format at any time with SDL_SetAudioStreamFormat(). * * \param devid an audio device to bind a stream to. * \param streams an array of audio streams to bind. * \param num_streams number streams listed in the `streams` array. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams); /** * Bind a single audio stream to an audio device. @@ -845,18 +968,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devi * * \param devid an audio device to bind a stream to. * \param stream an audio stream to bind to a device. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); /** * Unbind a list of audio streams from their audio devices. @@ -867,16 +990,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid * * Unbinding a stream that isn't bound to a device is a legal no-op. * - * \param streams an array of audio streams to unbind. + * \param streams an array of audio streams to unbind. Can be NULL or contain + * NULL. * \param num_streams number streams listed in the `streams` array. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams */ -extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams); /** * Unbind a single audio stream from its audio device. @@ -884,11 +1008,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **stream * This is a convenience function, equivalent to calling * `SDL_UnbindAudioStreams(&stream, 1)`. * - * \param stream an audio stream to unbind from a device. + * \param stream an audio stream to unbind from a device. Can be NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream */ @@ -907,7 +1031,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream * \sa SDL_BindAudioStreams @@ -924,7 +1048,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_GetAudioStreamData @@ -943,7 +1067,9 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream); @@ -953,17 +1079,17 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * \param stream the SDL_AudioStream to query. * \param src_spec where to store the input audio format; ignored if NULL. * \param dst_spec where to store the output audio format; ignored if NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); /** * Change the input and output formats of an audio stream. @@ -978,23 +1104,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *s * next sound file, and start putting that new data while the previous sound * file is still queued, and everything will still play back correctly. * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * * \param stream the stream the format is being changed. * \param src_spec the new format of the audio input; if NULL, it is not * changed. * \param dst_spec the new format of the audio output; if NULL, it is not * changed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFormat * \sa SDL_SetAudioStreamFrequencyRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** * Get the frequency ratio of an audio stream. @@ -1006,7 +1138,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *s * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFrequencyRatio */ @@ -1027,18 +1159,18 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \param stream the stream the frequency ratio is being changed. * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 * and 100. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Get the gain of an audio stream. @@ -1055,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioS * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGain */ @@ -1074,17 +1206,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \param stream the stream on which the gain is being changed. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); /** * Get the current input channel map of an audio stream. @@ -1104,7 +1236,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *str * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1128,7 +1260,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStr * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1148,8 +1280,12 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * Data that was previously queued in the stream will still be operated on in * the order that was current when it was added, which is to say you can put @@ -1164,26 +1300,31 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Set the current output channel map of an audio stream. @@ -1194,12 +1335,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * The output channel map reorders data that leaving a stream via * SDL_GetAudioStreamData. * - * Each item in the array represents an output channel, and its value is the + * Each item in the array represents an input channel, and its value is the * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * The output channel map can be changed at any time, as output remapping is * applied during SDL_GetAudioStreamData. @@ -1211,26 +1356,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Add data to the stream. @@ -1246,21 +1398,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_Audi * \param stream the stream the audio data is being added to. * \param buf a pointer to the audio data to add. * \param len the number of bytes to write to the stream. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but if the * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_FlushAudioStream * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); /** * Get converted/resampled data from the stream. @@ -1284,7 +1436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *str * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_GetAudioStreamAvailable @@ -1311,7 +1463,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamData * \sa SDL_PutAudioStreamData @@ -1322,6 +1474,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str /** * Get the number of bytes currently queued. * + * This is the number of bytes put into a stream as input, not the number that + * can be retrieved as output. Because of several details, it's not possible + * to calculate one number directly from the other. If you need to know how + * much usable data can be retrieved right now, you should use + * SDL_GetAudioStreamAvailable() and not this function. + * * Note that audio streams can change their input format at any time, even if * there is still data queued in a different format, so the returned byte * count will not necessarily match the number of _sample frames_ available. @@ -1344,7 +1502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_ClearAudioStream @@ -1361,16 +1519,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * input, so the complete output becomes available. * * \param stream the audio stream to flush. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** * Clear any pending data in the stream. @@ -1379,19 +1537,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *strea * stream until more is added. * * \param stream the audio stream to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamAvailable * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); /** * Use this function to pause audio playback on the audio device associated @@ -1406,16 +1564,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *strea * loading, etc. * * \param stream the audio stream associated with the audio device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); /** * Use this function to unpause audio playback on the audio device associated @@ -1426,16 +1584,36 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream * to progress again, and audio can be generated. * * \param stream the audio stream associated with the audio device to resume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to query if an audio device associated with a stream is + * paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * \param stream the audio stream associated with the audio device to query. + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream); + /** * Lock an audio stream for serialized access. @@ -1454,16 +1632,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream * all the same attributes (recursive locks are allowed, etc). * * \param stream the audio stream to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); /** @@ -1472,17 +1650,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream * This unlocks an audio stream after a call to SDL_LockAudioStream. * * \param stream the audio stream to unlock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety You should only call this from the same thread that * previously called SDL_LockAudioStream. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); /** * A callback that fires when data passes through an SDL_AudioStream. @@ -1519,7 +1697,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stre * is called, so your callback does not need to manage the lock * explicitly. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback * \sa SDL_SetAudioStreamPutCallback @@ -1561,16 +1739,16 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * from the stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamPutCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** * Set a callback that runs when data is added to an audio stream. @@ -1610,16 +1788,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStre * stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** @@ -1637,7 +1815,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStre * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -1699,7 +1877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamDevice * \sa SDL_ResumeAudioStreamDevice @@ -1737,7 +1915,7 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_Audi * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioPostmixCallback */ @@ -1788,14 +1966,14 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio * \param devid the ID of an opened audio device. * \param callback a callback function to be called. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); /** @@ -1839,7 +2017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * Example: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); + * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len); * ``` * * Note that the SDL_LoadWAV function does this same thing for you, but in a @@ -1850,19 +2028,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * ``` * * \param src the data source for the WAVE data. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE * data's format details on successful return. * \param audio_buf a pointer filled with the audio data, allocated by the * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1871,12 +2049,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Loads a WAV from a file path. @@ -1884,7 +2062,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * This is a convenience function that is effectively the same as: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), SDL_TRUE, spec, audio_buf, audio_len); + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); * ``` * * \param path the file path of the WAV file to open. @@ -1894,11 +2072,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1907,12 +2085,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Mix audio data in a specified format. @@ -1941,14 +2119,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * \param len the length of the audio buffer in bytes. * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full * audio volume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); /** * Convert some audio data of one format to another format. @@ -1971,14 +2149,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, * which should be freed with SDL_free(). On error, it will be * NULL. * \param dst_len will be filled with the len of dst_data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); /** * Get the human readable name of an audio format. @@ -1989,7 +2167,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); @@ -2005,7 +2183,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_begin_code.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_begin_code.h index f418c61..a6b47cf 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_begin_code.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_begin_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,15 @@ /* WIKI CATEGORY: BeginCode */ /** - * SDL_begin_code.h sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * # CategoryBeginCode + * + * `SDL_begin_code.h` sets things up for C dynamic library function + * definitions, static inlined functions, and structures aligned at 4-byte + * alignment. If you don't like ugly C preprocessor code, don't look at this + * file. :) + * + * SDL's headers use this; applications generally should not include this + * header directly. */ /* This shouldn't be nested -- included it around code only. */ @@ -33,6 +39,259 @@ #endif #define SDL_begin_code_h +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a symbol as deprecated. + * + * A function is marked deprecated by adding this macro to its declaration: + * + * ```c + * extern SDL_DEPRECATED int ThisFunctionWasABadIdea(void); + * ``` + * + * Compilers with deprecation support can give a warning when a deprecated + * function is used. This symbol may be used in SDL's headers, but apps are + * welcome to use it for their own interfaces as well. + * + * SDL, on occasion, might deprecate a function for various reasons. However, + * SDL never removes symbols before major versions, so deprecated interfaces + * in SDL3 will remain available until SDL4, where it would be expected an app + * would have to take steps to migrate anyhow. + * + * On compilers without a deprecation mechanism, this is defined to nothing, + * and using a deprecated function will not generate a warning. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEPRECATED __attribute__((deprecated)) + +/** + * A macro to tag a symbol as a public API. + * + * SDL uses this macro for all its public functions. On some targets, it is + * used to signal to the compiler that this function needs to be exported from + * a shared library, but it might have other side effects. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DECLSPEC __attribute__ ((visibility("default"))) + +/** + * A macro to set a function's calling conventions. + * + * SDL uses this macro for all its public functions, and any callbacks it + * defines. This macro guarantees that calling conventions match between SDL + * and the app, even if the two were built with different compilers or + * optimization settings. + * + * When writing a callback function, it is very important for it to be + * correctly tagged with SDLCALL, as mismatched calling conventions can cause + * strange behaviors and can be difficult to diagnose. Plus, on many + * platforms, SDLCALL is defined to nothing, so compilers won't be able to + * warn that the tag is missing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDLCALL __cdecl + +/** + * A macro to request a function be inlined. + * + * This is a hint to the compiler to inline a function. The compiler is free + * to ignore this request. On compilers without inline support, this is + * defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INLINE __inline + +/** + * A macro to demand a function be inlined. + * + * This is a command to the compiler to inline a function. SDL uses this macro + * in its public headers for a handful of simple functions. On compilers + * without forceinline support, this is defined to `static SDL_INLINE`, which + * is often good enough. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FORCE_INLINE __forceinline + +/** + * A macro to tag a function as never-returning. + * + * This is a hint to the compiler that a function does not return. An example + * of a function like this is the C runtime's exit() function. + * + * This hint can lead to code optimizations, and help analyzers understand + * code flow better. On compilers without noreturn support, this is defined to + * nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NORETURN __attribute__((noreturn)) + +/** + * A macro to tag a function as never-returning (for analysis purposes). + * + * This is almost identical to SDL_NORETURN, except functions marked with this + * _can_ actually return. The difference is that this isn't used for code + * generation, but rather static analyzers use this information to assume + * truths about program state and available code paths. Specifically, this tag + * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this + * tag behind the scenes. Generally, apps that don't understand the specific + * use-case for this tag should avoid using it directly. + * + * On compilers without analyzer_noreturn support, this is defined to nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) + + +/** + * A macro to signal that a case statement without a `break` is intentional. + * + * C compilers have gotten more aggressive about warning when a switch's + * `case` block does not end with a `break` or other flow control statement, + * flowing into the next case's code, as this is a common accident that leads + * to strange bugs. But sometimes falling through to the next case is the + * correct and desired behavior. This symbol lets an app communicate this + * intention to the compiler, so it doesn't generate a warning. + * + * It is used like this: + * + * ```c + * switch (x) { + * case 1: + * DoSomethingOnlyForOne(); + * SDL_FALLTHROUGH; // tell the compiler this was intentional. + * case 2: + * DoSomethingForOneAndTwo(); + * break; + * } + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FALLTHROUGH [[fallthrough]] + +/** + * A macro to tag a function's return value as critical. + * + * This is a hint to the compiler that a function's return value should not be + * ignored. + * + * If an NODISCARD function's return value is thrown away (the function is + * called as if it returns `void`), the compiler will issue a warning. + * + * While it's generally good practice to check return values for errors, often + * times legitimate programs do not for good reasons. Be careful about what + * functions are tagged as NODISCARD. It operates best when used on a function + * that's failure is surprising and catastrophic; a good example would be a + * program that checks the return values of all its file write function calls + * but not the call to close the file, which it assumes incorrectly never + * fails. + * + * Function callers that want to throw away a NODISCARD return value can call + * the function with a `(void)` cast, which informs the compiler the act is + * intentional. + * + * On compilers without nodiscard support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NODISCARD [[nodiscard]] + +/** + * A macro to tag a function as an allocator. + * + * This is a hint to the compiler that a function is an allocator, like + * malloc(), with certain rules. A description of how GCC treats this hint is + * here: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute + * + * On compilers without allocator tag support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) + +/** + * A macro to tag a function as returning a certain allocation. + * + * This is a hint to the compiler that a function allocates and returns a + * specific amount of memory based on one of its arguments. For example, the C + * runtime's malloc() function could use this macro with an argument of 1 + * (first argument to malloc is the size of the allocation). + * + * On compilers without alloc_size support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) + +/** + * A macro to tag a pointer variable, to help with pointer aliasing. + * + * A good explanation of the restrict keyword is here: + * + * https://en.wikipedia.org/wiki/Restrict + * + * On compilers without restrict support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_RESTRICT __restrict__ + +/** + * Check if the compiler supports a given builtin functionality. + * + * This allows preprocessor checks for things that otherwise might fail to + * compile. + * + * Supported by virtually all clang versions and more-recent GCCs. Use this + * instead of checking the clang version if possible. + * + * On compilers without has_builtin support, this is defined to 0 (always + * false). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAS_BUILTIN(x) __has_builtin(x) + +/* end of wiki documentation section. */ +#endif + +#ifndef SDL_HAS_BUILTIN +#ifdef __has_builtin +#define SDL_HAS_BUILTIN(x) __has_builtin(x) +#else +#define SDL_HAS_BUILTIN(x) 0 +#endif +#endif + #ifndef SDL_DEPRECATED # if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ # define SDL_DEPRECATED __attribute__((deprecated)) @@ -53,7 +312,7 @@ /* Some compilers use a special export keyword */ #ifndef SDL_DECLSPEC -# if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_CYGWIN) || defined(SDL_PLATFORM_GDK) +# if defined(SDL_PLATFORM_WINDOWS) # ifdef DLL_EXPORT # define SDL_DECLSPEC __declspec(dllexport) # else @@ -70,7 +329,7 @@ /* By default SDL uses the C calling convention */ #ifndef SDLCALL -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_GDK)) && !defined(__GNUC__) +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) #define SDLCALL __cdecl #else #define SDLCALL diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_bits.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_bits.h index 72be082..7435ce6 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_bits.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_bits.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -36,10 +36,6 @@ extern "C" { #endif -/** - * \file SDL_bits.h - */ - #if defined(__WATCOMC__) && defined(__386__) extern __inline int _SDL_bsr_watcom(Uint32); #pragma aux _SDL_bsr_watcom = \ @@ -65,7 +61,7 @@ extern __inline int _SDL_bsr_watcom(Uint32); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { @@ -82,10 +78,10 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) return -1; } return _SDL_bsr_watcom(x); -#elif defined(_MSC_VER) +#elif defined(_MSC_VER) && _MSC_VER >= 1400 unsigned long index; if (_BitScanReverse(&index, x)) { - return index; + return (int)index; } return -1; #else @@ -120,8 +116,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * Determine if a unsigned 32-bit value has exactly one bit set. * * If there are no bits set (`x` is zero), or more than one bit set, this - * returns SDL_FALSE. If any one bit is exclusively set, this returns - * SDL_TRUE. + * returns false. If any one bit is exclusively set, this returns true. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is @@ -129,18 +124,18 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine. - * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. + * \returns true if exactly one bit is set in `x`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_HasExactlyOneBitSet32(Uint32 x) +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_blendmode.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_blendmode.h index 76aa197..8f00cbc 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_blendmode.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_blendmode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,7 @@ * * Blend modes decide how two colors will mix together. There are both * standard modes for basic needs and a means to create custom modes, - * dictating what sort of math to do what on what color components. + * dictating what sort of math to do on what color components. */ #ifndef SDL_blendmode_h_ @@ -45,7 +45,7 @@ extern "C" { * * Additional values may be obtained from SDL_ComposeCustomBlendMode. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_ComposeCustomBlendMode */ @@ -64,7 +64,7 @@ typedef Uint32 SDL_BlendMode; * The blend operation used when combining source and destination pixel * components. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendOperation { @@ -83,7 +83,7 @@ typedef enum SDL_BlendOperation * operation. The comma-separated factors listed above are always applied in * the component order red, green, blue, and alpha. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendFactor { @@ -177,7 +177,9 @@ typedef enum SDL_BlendFactor * \returns an SDL_BlendMode that represents the chosen factors and * operations. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode * \sa SDL_GetRenderDrawBlendMode diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_camera.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_camera.h index 3d4c57e..c4d0596 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_camera.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_camera.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -28,13 +28,51 @@ * devices can be enumerated, queried, and opened. Once opened, it will * provide SDL_Surface objects as new frames of video come in. These surfaces * can be uploaded to an SDL_Texture or processed as pixels in memory. + * + * Several platforms will alert the user if an app tries to access a camera, + * and some will present a UI asking the user if your application should be + * allowed to obtain images at all, which they can deny. A successfully opened + * camera will not provide images until permission is granted. Applications, + * after opening a camera device, can see if they were granted access by + * either polling with the SDL_GetCameraPermissionState() function, or waiting + * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED + * event. Platforms that don't have any user approval process will report + * approval immediately. + * + * Note that SDL cameras only provide video as individual frames; they will + * not provide full-motion video encoded in a movie file format, although an + * app is free to encode the acquired frames into any format it likes. It also + * does not provide audio from the camera hardware through this API; not only + * do many webcams not have microphones at all, many people--from streamers to + * people on Zoom calls--will want to use a separate microphone regardless of + * the camera. In any case, recorded audio will be available through SDL's + * audio API no matter what hardware provides the microphone. + * + * ## Camera gotchas + * + * Consumer-level camera hardware tends to take a little while to warm up, + * once the device has been opened. Generally most camera apps have some sort + * of UI to take a picture (a button to snap a pic while a preview is showing, + * some sort of multi-second countdown for the user to pose, like a photo + * booth), which puts control in the users' hands, or they are intended to + * stay on for long times (Pokemon Go, etc). + * + * It's not uncommon that a newly-opened camera will provide a couple of + * completely black frames, maybe followed by some under-exposed images. If + * taking a single frame automatically, or recording video from a camera's + * input without the user initiating it from a preview, it could be wise to + * drop the first several frames (if not the first several _seconds_ worth of + * frames!) before using images from a camera. */ #ifndef SDL_camera_h_ #define SDL_camera_h_ +#include #include -#include +#include +#include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -50,7 +88,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -59,7 +97,7 @@ typedef Uint32 SDL_CameraID; /** * The opaque structure used to identify an opened SDL camera. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Camera SDL_Camera; @@ -69,7 +107,7 @@ typedef struct SDL_Camera SDL_Camera; * Cameras often support multiple formats; each one will be encapsulated in * this struct. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetCameraSupportedFormats * \sa SDL_GetCameraFormat @@ -87,7 +125,7 @@ typedef struct SDL_CameraSpec /** * The position of camera in relation to system device. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCameraPosition */ @@ -116,7 +154,7 @@ typedef enum SDL_CameraPosition * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameraDriver */ @@ -140,7 +178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumCameraDrivers */ @@ -158,7 +196,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); @@ -173,7 +211,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -211,7 +249,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_OpenCamera @@ -227,7 +265,7 @@ extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -246,7 +284,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -265,7 +303,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * You can call SDL_GetCameraFormat() to get the actual data format if passing * a NULL spec here. You can see the exact specs a device can support without - * conversion with SDL_GetCameraSupportedSpecs(). + * conversion with SDL_GetCameraSupportedFormats(). * * SDL will not attempt to emulate framerate; it will try to set the hardware * to the rate closest to the requested speed, but it won't attempt to limit @@ -278,10 +316,11 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * the camera, and they can choose Yes or No at that point. Until they do, the * camera will not be usable. The app should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On - * platforms that don't require explicit user approval (and perhaps in places - * where the user previously permitted access), the approval event might come - * immediately, but it might come seconds, minutes, or hours later! + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. On platforms that don't require explicit user approval (and + * perhaps in places where the user previously permitted access), the approval + * event might come immediately, but it might come seconds, minutes, or hours + * later! * * \param instance_id the camera device instance ID. * \param spec the desired format for data the device will provide. Can be @@ -291,7 +330,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_GetCameraFormat @@ -324,7 +363,7 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera * \sa SDL_CloseCamera @@ -340,7 +379,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -355,7 +394,7 @@ extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera); @@ -366,23 +405,24 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * be converting to this format behind the scenes. * * If the system is waiting for the user to approve access to the camera, as - * some platforms require, this will return SDL_FALSE, but this isn't - * necessarily a fatal error; you should either wait for an + * some platforms require, this will return false, but this isn't necessarily + * a fatal error; you should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. * * \param camera opened camera device. * \param spec the SDL_CameraSpec to be initialized by this function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); /** * Acquire a frame. @@ -404,14 +444,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * After use, the frame should be released with SDL_ReleaseCameraFrame(). If * you don't do this, the system may stop providing more video! * - * Do not call SDL_FreeSurface() on the returned surface! It must be given + * Do not call SDL_DestroySurface() on the returned surface! It must be given * back to the camera subsystem with SDL_ReleaseCameraFrame! * * If the system is waiting for the user to approve access to the camera, as * some platforms require, this will return NULL (no frames available); you * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or - * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() - * occasionally until it returns non-zero. + * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll + * SDL_GetCameraPermissionState() occasionally until it returns non-zero. * * \param camera opened camera device. * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on @@ -421,7 +461,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReleaseCameraFrame */ @@ -449,7 +489,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireCameraFrame */ @@ -464,9 +504,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_ * \threadsafety It is safe to call this function from any thread, but no * thread may reference `device` once this function is called. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_OpenCameraWithSpec * \sa SDL_OpenCamera */ extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_clipboard.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_clipboard.h index 4d4ae32..0d3cbb4 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_clipboard.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_clipboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,51 @@ * from other processes and publishing information of its own. * * This is not just text! SDL apps can access and publish data by mimetype. + * + * ## Basic use (text) + * + * Obtaining and publishing simple text to the system clipboard is as easy as + * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively. + * These deal with C strings in UTF-8 encoding. Data transmission and encoding + * conversion is completely managed by SDL. + * + * ## Clipboard callbacks (data other than text) + * + * Things get more complicated when the clipboard contains something other + * than text. Not only can the system clipboard contain data of any type, in + * some cases it can contain the same data in different formats! For example, + * an image painting app might let the user copy a graphic to the clipboard, + * and offers it in .BMP, .JPG, or .PNG format for other apps to consume. + * + * Obtaining clipboard data ("pasting") like this is a matter of calling + * SDL_GetClipboardData() and telling it the mimetype of the data you want. + * But how does one know if that format is available? SDL_HasClipboardData() + * can report if a specific mimetype is offered, and + * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes + * available, so the app can decide what to do with the data and what formats + * it can support. + * + * Setting the clipboard ("copying") to arbitrary data is done with + * SDL_SetClipboardData. The app does not provide the data in this call, but + * rather the mimetypes it is willing to provide and a callback function. + * During the callback, the app will generate the data. This allows massive + * data sets to be provided to the clipboard, without any data being copied + * before it is explicitly requested. More specifically, it allows an app to + * offer data in multiple formats without providing a copy of all of them + * upfront. If the app has an image that it could provide in PNG or JPG + * format, it doesn't have to encode it to either of those unless and until + * something tries to paste it. + * + * ## Primary Selection + * + * The X11 and Wayland video targets have a concept of the "primary selection" + * in addition to the usual clipboard. This is generally highlighted (but not + * explicitly copied) text from various apps. SDL offers APIs for this through + * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers + * these APIs on platforms without this concept, too, but only so far that it + * will keep a copy of a string that the app sets for later retrieval; the + * operating system will not ever attempt to change the string externally if + * it doesn't support a primary selection. */ #ifndef SDL_clipboard_h_ @@ -46,27 +91,31 @@ extern "C" { * Put UTF-8 text into the clipboard. * * \param text the text to store in the clipboard. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_HasClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); /** * Get UTF-8 text from the clipboard. * - * This functions returns empty string if there was not enough memory left for - * a copy of the clipboard's content. + * This functions returns an empty string if there was 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 * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardText * \sa SDL_SetClipboardText @@ -76,40 +125,46 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); /** * Query whether the clipboard exists and contains a non-empty text string. * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * \returns true if the clipboard has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_SetClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * * \param text the text to store in the primary selection. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_HasPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPrimarySelectionText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); /** * Get UTF-8 text from the primary selection. * - * This functions returns empty string if there was not enough memory left for - * a copy of the primary selection's content. + * This functions returns an empty string if there was 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 * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasPrimarySelectionText * \sa SDL_SetPrimarySelectionText @@ -120,15 +175,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * Query whether the primary selection exists and contains a non-empty text * string. * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. + * \returns true if the primary selection has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_SetPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); /** * Callback function that will be called when data for the specified mime-type @@ -148,7 +204,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); * breakage in receiving applications. 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.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -160,7 +216,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c * * \param userdata a pointer to provided user data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -170,13 +226,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * Offer clipboard data to the OS. * * Tell the operating system that the application is offering clipboard data - * for each of the proivded mime-types. Once another application requests the - * data the callback function will be called allowing it to generate and + * for each of the provided mime-types. Once another application requests the + * data the callback function will be called, allowing it to generate and * 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 - * document) + * document). * * \param callback a function pointer to the function that provides the * clipboard data. @@ -185,28 +241,32 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \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 num_mime_types the number of mime-types in the mime_types list. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearClipboardData * \sa SDL_GetClipboardData * \sa SDL_HasClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** * Clear the clipboard data. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); /** * Get the data from clipboard for a given mime type. @@ -220,7 +280,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); * for more information. This should be freed with SDL_free() when it * is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardData * \sa SDL_SetClipboardData @@ -231,15 +293,34 @@ 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 SDL_TRUE if there exists data in clipboard for the provided mime - * type, SDL_FALSE if it does not. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData * \sa SDL_GetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \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 + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_close_code.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_close_code.h index fa4d3d1..da1dea7 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_close_code.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_close_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -21,7 +21,10 @@ /* * This file reverses the effects of SDL_begin_code.h and should be included - * after you finish any function and structure declarations in your headers + * after you finish any function and structure declarations in your headers. + * + * SDL's headers use this; applications generally should not include this + * header directly. */ #ifndef SDL_begin_code_h diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_copying.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_copying.h index dcbdcea..747bd35 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_copying.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_copying.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_cpuinfo.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_cpuinfo.h index e7ced26..1745bd9 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_cpuinfo.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_cpuinfo.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,6 +29,12 @@ * These functions are largely concerned with reporting if the system has * access to various SIMD instruction sets, but also has other important info * to share, such as system RAM size and number of logical CPU cores. + * + * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are + * available on all platforms, even if they don't make sense (an ARM processor + * will never have SSE and an x86 processor will never have NEON, for example, + * but these functions still exist and will simply return false in these + * cases). */ #ifndef SDL_cpuinfo_h_ @@ -49,20 +55,22 @@ extern "C" { * processors have a 128 byte cache line. We use the larger value to be * generally safe. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CACHELINE_SIZE 128 /** - * Get the number of CPU cores available. + * Get the number of logical CPU cores available. * * \returns the total number of logical CPU cores. On CPUs that include * technologies such as hyperthreading, the number of logical cores * may be more than the number of physical cores. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); /** * Determine the L1 cache line size of the CPU. @@ -72,7 +80,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); * * \returns the L1 cache line size of the CPU, in bytes. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); @@ -82,144 +92,164 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * This always returns false on CPUs that aren't using PowerPC instruction * sets. * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. + * \returns true if the CPU has AltiVec features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); /** * Determine whether the CPU has MMX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. + * \returns true if the CPU has MMX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); /** * Determine whether the CPU has SSE features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. + * \returns true if the CPU has SSE features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); /** * Determine whether the CPU has SSE2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); /** * Determine whether the CPU has SSE3 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. + * \returns true if the CPU has SSE3 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); /** * Determine whether the CPU has SSE4.1 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.1 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); /** * Determine whether the CPU has SSE4.2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); /** * Determine whether the CPU has AVX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. + * \returns true if the CPU has AVX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX2 * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); /** * Determine whether the CPU has AVX2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. + * \returns true if the CPU has AVX2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); /** * Determine whether the CPU has AVX-512F (foundation) features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. + * \returns true if the CPU has AVX-512F features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX2 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); /** * Determine whether the CPU has ARM SIMD (ARMv6) features. @@ -228,24 +258,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. + * \returns true if the CPU has ARM SIMD features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasNEON */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); /** * Determine whether the CPU has NEON (ARM SIMD) features. * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. + * \returns true if the CPU has ARM NEON features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); /** * Determine whether the CPU has LSX (LOONGARCH SIMD) features. @@ -253,12 +287,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LSX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); /** * Determine whether the CPU has LASX (LOONGARCH SIMD) features. @@ -266,19 +301,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LASX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); /** * Get the amount of RAM configured in the system. * * \returns the amount of RAM configured in the system in MiB. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); @@ -297,7 +335,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); * \returns the alignment in bytes needed for available, known SIMD * instructions. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc * \sa SDL_aligned_free diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_dialog.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_dialog.h index 8a198a8..460038f 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_dialog.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_dialog.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,12 +23,23 @@ * # CategoryDialog * * File dialog support. + * + * SDL offers file dialogs, to let users select files with native GUI + * interfaces. There are "open" dialogs, "save" dialogs, and folder selection + * dialogs. The app can control some details, such as filtering to specific + * files, or whether multiple files can be selected by the user. + * + * Note that launching a file dialog is a non-blocking operation; control + * returns to the app immediately, and a callback is called later (possibly in + * another thread) when the user makes a choice. */ #ifndef SDL_dialog_h_ #define SDL_dialog_h_ +#include #include +#include #include #include @@ -48,12 +59,13 @@ extern "C" { * hyphens, underscores and periods. Alternatively, the whole string can be a * single asterisk ("*"), which serves as an "All files" filter. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef struct SDL_DialogFileFilter { @@ -75,31 +87,34 @@ typedef struct SDL_DialogFileFilter * is a null-terminated list of pointers to C strings, each containing a * path. * - * The filelist argument does not need to be freed; it will automatically be - * freed when the callback returns. + * The filelist argument should not be freed; it will automatically be freed + * when the callback returns. * * The filter argument is the index of the filter that was selected, or -1 if * no filter was selected or if the platform or method doesn't support * fetching the selected filter. * + * In Android, the `filelist` are `content://` URIs. They should be opened + * using SDL_IOFromFile() with appropriate modes. This applies both to open + * and save file dialog. + * * \param userdata an app-provided pointer, for the callback's use. * \param filelist the file(s) chosen by the user. * \param filter index of the selected filter. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter); /** * Displays a dialog that lets the user select a file on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -117,47 +132,41 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); /** * Displays a dialog that lets the user choose a new or existing file on their * filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -174,44 +183,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); /** * Displays a dialog that lets the user select a folder on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -229,31 +232,105 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is always -1 for SDL_ShowOpenFolderDialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \param window the window that the dialog should be modal for, may be NULL. * Not all platforms support this option. - * \param default_location the default folder or file to start the dialog at. - * May be NULL. Not all platforms support this option. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); + +/** + * Various types of file dialogs. + * + * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of + * dialog to present to the user. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ShowFileDialogWithProperties + */ +typedef enum SDL_FileDialogType +{ + SDL_FILEDIALOG_OPENFILE, + SDL_FILEDIALOG_SAVEFILE, + SDL_FILEDIALOG_OPENFOLDER +} SDL_FileDialogType; + +/** + * Create and launch a file dialog with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of + * SDL_DialogFileFilter structs, which will be used as filters for + * file-based selections. Ignored if the dialog is an "Open Folder" dialog. + * If non-NULL, the array of filters must remain valid at least until the + * callback is invoked. + * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the + * array of filters, if it exists. + * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should + * be modal for. + * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to + * start the dialog at. + * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select + * more than one entry. + * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. + * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button + * should have. + * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button + * should have. + * + * Note that each platform may or may not support any of the properties. + * + * \param type the type of file dialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param props the properties to use. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FileDialogType + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); + +#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" +#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" +#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" +#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" +#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" +#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" +#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" +#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -261,4 +338,4 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback #endif #include -#endif /* SDL_joystick_h_ */ +#endif /* SDL_dialog_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_egl.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_egl.h index cc557d6..65d4e96 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_egl.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_egl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_endian.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_endian.h index cb3d7f3..a34e9d4 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_endian.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_endian.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,20 @@ /** * # CategoryEndian * - * Functions for reading and writing endian-specific values. + * Functions converting endian-specific values to different byte orders. + * + * These functions either unconditionally swap byte order (SDL_Swap16, + * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's + * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, + * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the + * latter case, the functionality is provided by macros that become no-ops if + * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE + * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC + * processor (bigendian), the macros behavior is reversed. + * + * The swap routines are inline functions, and attempt to use compiler + * intrinsics, inline assembly, and other magic to make byteswapping + * efficient. */ #ifndef SDL_endian_h_ @@ -51,12 +64,71 @@ _m_prefetch(void *__P) * \name The two types of endianness */ /* @{ */ + + +/** + * A value to represent littleendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_LIL_ENDIAN + * SDL_Log("This system is littleendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_BIG_ENDIAN + */ #define SDL_LIL_ENDIAN 1234 + +/** + * A value to represent bigendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_LIL_ENDIAN + */ #define SDL_BIG_ENDIAN 4321 + /* @} */ #ifndef SDL_BYTEORDER -#ifdef SDL_PLATFORM_LINUX +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's byte order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +#elif defined(SDL_PLATFORM_LINUX) #include #define SDL_BYTEORDER __BYTE_ORDER #elif defined(SDL_PLATFORM_SOLARIS) @@ -97,8 +169,29 @@ _m_prefetch(void *__P) #endif /* !SDL_BYTEORDER */ #ifndef SDL_FLOATWORDORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's floating point word order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN + * SDL_Log("This system's floats are bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN /* predefs from newer gcc versions: */ -#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) #if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) #define SDL_FLOATWORDORDER SDL_LIL_ENDIAN #elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) @@ -125,10 +218,6 @@ _m_prefetch(void *__P) extern "C" { #endif -/** - * \file SDL_endian.h - */ - /* various modern compilers may have builtin swap */ #if defined(__GNUC__) || defined(__clang__) # define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \ @@ -148,6 +237,7 @@ extern "C" { #endif /* Byte swap 16-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP16 #define SDL_Swap16(x) __builtin_bswap16(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -191,8 +281,10 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); } #endif +#endif /* Byte swap 32-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP32 #define SDL_Swap32(x) __builtin_bswap32(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -239,8 +331,10 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) ((x >> 8) & 0x0000FF00) | (x >> 24))); } #endif +#endif /* Byte swap 64-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP64 #define SDL_Swap64(x) __builtin_bswap64(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -290,7 +384,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) return (x); } #endif - +#endif /** * Byte-swap a floating point number. @@ -309,7 +403,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { @@ -348,7 +442,7 @@ SDL_FORCE_INLINE float SDL_SwapFloat(float x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } @@ -369,7 +463,7 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } @@ -390,7 +484,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } @@ -404,7 +498,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16LE(x) SwapOnlyIfNecessary(x) @@ -418,7 +514,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32LE(x) SwapOnlyIfNecessary(x) @@ -432,7 +530,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64LE(x) SwapOnlyIfNecessary(x) @@ -446,7 +546,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x) @@ -460,7 +562,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16BE(x) SwapOnlyIfNecessary(x) @@ -474,7 +578,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32BE(x) SwapOnlyIfNecessary(x) @@ -488,7 +594,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64BE(x) SwapOnlyIfNecessary(x) @@ -502,7 +610,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x) diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_error.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_error.h index a98823f..934967c 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_error.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_error.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,26 @@ * # CategoryError * * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. */ #ifndef SDL_error_h_ @@ -44,8 +64,8 @@ extern "C" { * * Calling this function will replace any previous error message that was set. * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: * * ```c * if (error_code) { @@ -56,25 +76,49 @@ extern "C" { * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if * any. - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_GetError + * \sa SDL_SetErrorV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * \param fmt a printf()-style message format string. + * \param ap a variable argument list. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1); /** * Set an error indicating that memory allocation failed. * * This function does not do any memory allocation. * - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); /** * Retrieve a message about the last error that occurred on the current @@ -104,7 +148,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); * or an empty string if there hasn't been an error message set since * the last call to SDL_ClearError(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_SetError @@ -114,14 +160,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); /** * Clear any previous error message for this thread. * - * \returns SDL_TRUE. + * \returns true. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetError * \sa SDL_SetError */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); /** * \name Internal error functions @@ -130,8 +178,43 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); * Private error reporting function - used internally. */ /* @{ */ + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_Unsupported() SDL_SetError("That operation is not supported") + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * A common usage pattern inside SDL is this: + * + * ```c + * bool MyFunction(const char *str) { + * if (!str) { + * return SDL_InvalidParamError("str"); // returns false. + * } + * DoSomething(str); + * return true; + * } + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + /* @} *//* Internal error functions */ /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_events.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_events.h index fbe2bb0..1323e9f 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_events.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_events.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,22 +23,50 @@ * # CategoryEvents * * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. */ #ifndef SDL_events_h_ #define SDL_events_h_ +#include #include +#include #include #include #include #include +#include #include #include -#include +#include +#include +#include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,29 +76,10 @@ extern "C" { /* General keyboard/mouse/pen state definitions */ -/** - * A value that signifies a button is no longer pressed. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_PRESSED - */ -#define SDL_RELEASED 0 - -/** - * A value that signifies a button has been pressed down. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_RELEASED - */ -#define SDL_PRESSED 1 - - /** * The types of events that can be delivered. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_EventType { @@ -148,7 +157,7 @@ typedef enum SDL_EventType SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */ SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */ SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled - in an event watcher, the window handle is still valid and can still be used to retrieve any userdata + in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid */ SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ @@ -203,6 +212,7 @@ typedef enum SDL_EventType SDL_EVENT_FINGER_DOWN = 0x700, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, + SDL_EVENT_FINGER_CANCELED, /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ @@ -243,6 +253,13 @@ typedef enum SDL_EventType /* Render events */ SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ + SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + SDL_EVENT_PRIVATE0 = 0x4000, + SDL_EVENT_PRIVATE1, + SDL_EVENT_PRIVATE2, + SDL_EVENT_PRIVATE3, /* Internal events */ SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ @@ -265,7 +282,7 @@ typedef enum SDL_EventType /** * Fields shared by every event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CommonEvent { @@ -277,7 +294,7 @@ typedef struct SDL_CommonEvent /** * Display state change event data (event.display.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DisplayEvent { @@ -292,7 +309,7 @@ typedef struct SDL_DisplayEvent /** * Window state change event data (event.window.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_WindowEvent { @@ -307,7 +324,7 @@ typedef struct SDL_WindowEvent /** * Keyboard device event structure (event.kdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_KeyboardDeviceEvent { @@ -326,7 +343,7 @@ typedef struct SDL_KeyboardDeviceEvent * event scancode and modifiers directly from the keyboard layout, bypassing * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_HINT_KEYCODE_OPTIONS @@ -342,8 +359,8 @@ typedef struct SDL_KeyboardEvent SDL_Keycode key; /**< SDL virtual key code */ SDL_Keymod mod; /**< current key modifiers */ Uint16 raw; /**< The platform dependent scancode for this event */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ } SDL_KeyboardEvent; /** @@ -353,7 +370,7 @@ typedef struct SDL_KeyboardEvent * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingEvent { @@ -369,7 +386,7 @@ typedef struct SDL_TextEditingEvent /** * Keyboard IME candidates event structure (event.edit_candidates.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingCandidatesEvent { @@ -380,7 +397,10 @@ typedef struct SDL_TextEditingCandidatesEvent const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ Sint32 num_candidates; /**< The number of strings in `candidates` */ Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ - SDL_bool horizontal; /**< SDL_TRUE if the list is horizontal, SDL_FALSE if it's vertical */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_TextEditingCandidatesEvent; /** @@ -389,7 +409,7 @@ typedef struct SDL_TextEditingCandidatesEvent * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput @@ -406,7 +426,7 @@ typedef struct SDL_TextInputEvent /** * Mouse device event structure (event.mdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseDeviceEvent { @@ -419,7 +439,7 @@ typedef struct SDL_MouseDeviceEvent /** * Mouse motion event structure (event.motion.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseMotionEvent { @@ -427,7 +447,7 @@ typedef struct SDL_MouseMotionEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id or SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ SDL_MouseButtonFlags state; /**< The current button state */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ @@ -438,7 +458,7 @@ typedef struct SDL_MouseMotionEvent /** * Mouse button event structure (event.button.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseButtonEvent { @@ -446,9 +466,9 @@ typedef struct SDL_MouseButtonEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding; float x; /**< X coordinate, relative to window */ @@ -458,7 +478,7 @@ typedef struct SDL_MouseButtonEvent /** * Mouse wheel event structure (event.wheel.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseWheelEvent { @@ -466,7 +486,7 @@ typedef struct SDL_MouseWheelEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */ float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ @@ -477,7 +497,7 @@ typedef struct SDL_MouseWheelEvent /** * Joystick axis motion event structure (event.jaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyAxisEvent { @@ -496,7 +516,7 @@ typedef struct SDL_JoyAxisEvent /** * Joystick trackball motion event structure (event.jball.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBallEvent { @@ -515,7 +535,7 @@ typedef struct SDL_JoyBallEvent /** * Joystick hat position change event structure (event.jhat.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyHatEvent { @@ -538,7 +558,7 @@ typedef struct SDL_JoyHatEvent /** * Joystick button event structure (event.jbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyButtonEvent { @@ -547,7 +567,7 @@ typedef struct SDL_JoyButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; @@ -555,7 +575,12 @@ typedef struct SDL_JoyButtonEvent /** * Joystick device event structure (event.jdevice.*) * - * \since This struct is available since SDL 3.0.0. + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GamepadDeviceEvent */ typedef struct SDL_JoyDeviceEvent { @@ -566,9 +591,9 @@ typedef struct SDL_JoyDeviceEvent } SDL_JoyDeviceEvent; /** - * Joysick battery level change event structure (event.jbattery.*) + * Joystick battery level change event structure (event.jbattery.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBatteryEvent { @@ -583,7 +608,7 @@ typedef struct SDL_JoyBatteryEvent /** * Gamepad axis motion event structure (event.gaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadAxisEvent { @@ -603,7 +628,7 @@ typedef struct SDL_GamepadAxisEvent /** * Gamepad button event structure (event.gbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadButtonEvent { @@ -612,7 +637,7 @@ typedef struct SDL_GamepadButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_GamepadButtonEvent; @@ -621,7 +646,16 @@ typedef struct SDL_GamepadButtonEvent /** * Gamepad device event structure (event.gdevice.*) * - * \since This struct is available since SDL 3.0.0. + * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent + * and an SDL_GamepadDeviceEvent. + * + * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged + * in during SDL_Init() and are recognized as gamepads. It will also send + * events for joysticks that get gamepad mappings at runtime. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_JoyDeviceEvent */ typedef struct SDL_GamepadDeviceEvent { @@ -634,7 +668,7 @@ typedef struct SDL_GamepadDeviceEvent /** * Gamepad touchpad event structure (event.gtouchpad.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadTouchpadEvent { @@ -652,7 +686,7 @@ typedef struct SDL_GamepadTouchpadEvent /** * Gamepad sensor event structure (event.gsensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadSensorEvent { @@ -668,7 +702,7 @@ typedef struct SDL_GamepadSensorEvent /** * Audio device event structure (event.adevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AudioDeviceEvent { @@ -676,7 +710,7 @@ typedef struct SDL_AudioDeviceEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ - Uint8 recording; /**< zero if a playback device, non-zero if a recording device. */ + bool recording; /**< false if a playback device, true if a recording device. */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -685,7 +719,7 @@ typedef struct SDL_AudioDeviceEvent /** * Camera device event structure (event.cdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CameraDeviceEvent { @@ -695,14 +729,43 @@ typedef struct SDL_CameraDeviceEvent SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ } SDL_CameraDeviceEvent; + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RenderEvent +{ + SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window containing the renderer in question. */ +} SDL_RenderEvent; + + /** * Touch finger event structure (event.tfinger.*) * - * \since This struct is available since SDL 3.0.0. + * Coordinates in this event are normalized. `x` and `y` are normalized to a + * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top + * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are + * normalized in the ranges of -1.0f (traversed all the way from the bottom or + * right to all the way up or left) to 1.0f (traversed all the way from the + * top or left to all the way down or right). + * + * Note that while the coordinates are _normalized_, they are not _clamped_, + * which means in some circumstances you can get a value outside of this + * range. For example, a renderer using logical presentation might give a + * negative value when the touch is in the letterboxing. Some platforms might + * report a touch outside of the window, which will also be outside of the + * range. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TouchFingerEvent { - SDL_EventType type; /**< SDL_EVENT_FINGER_MOTION or SDL_EVENT_FINGER_DOWN or SDL_EVENT_FINGER_UP */ + SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_TouchID touchID; /**< The touch device id */ @@ -728,14 +791,14 @@ typedef struct SDL_TouchFingerEvent * is there." The pen touching and lifting off from the tablet while not * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenProximityEvent { SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ } SDL_PenProximityEvent; @@ -748,18 +811,18 @@ typedef struct SDL_PenProximityEvent * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when * dealing with pen motion. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenMotionEvent { SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ } SDL_PenMotionEvent; /** @@ -768,7 +831,7 @@ typedef struct SDL_PenMotionEvent * These events come when a pen touches a surface (a tablet, etc), or lifts * off from one. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenTouchEvent { @@ -778,10 +841,10 @@ typedef struct SDL_PenTouchEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ - Uint8 eraser; /**< Non-zero if eraser end is used (not all pens support this). */ - Uint8 state; /**< SDL_PRESSED (pen is touching) or SDL_RELEASED (pen is lifted off) */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ } SDL_PenTouchEvent; /** @@ -790,7 +853,7 @@ typedef struct SDL_PenTouchEvent * This is for buttons on the pen itself that the user might click. The pen * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenButtonEvent { @@ -800,10 +863,10 @@ typedef struct SDL_PenButtonEvent SDL_WindowID windowID; /**< The window with mouse focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ Uint8 button; /**< The pen button index (first button is 1). */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ } SDL_PenButtonEvent; /** @@ -812,7 +875,7 @@ typedef struct SDL_PenButtonEvent * You might get some of these events even if the pen isn't touching the * tablet. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenAxisEvent { @@ -822,8 +885,8 @@ typedef struct SDL_PenAxisEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ SDL_PenAxis axis; /**< Axis that has changed */ float value; /**< New value of axis */ } SDL_PenAxisEvent; @@ -832,7 +895,7 @@ typedef struct SDL_PenAxisEvent * An event used to drop text or request a file open by the system * (event.drop.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DropEvent { @@ -850,19 +913,22 @@ typedef struct SDL_DropEvent * An event triggered when the clipboard contents have changed * (event.clipboard.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_ClipboardEvent { SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + bool owner; /**< are we owning the clipboard (internal update) */ + Sint32 num_mime_types; /**< number of mime types */ + const char **mime_types; /**< current mime types */ } SDL_ClipboardEvent; /** * Sensor event structure (event.sensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_SensorEvent { @@ -877,7 +943,7 @@ typedef struct SDL_SensorEvent /** * The "quit requested" event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_QuitEvent { @@ -895,7 +961,7 @@ typedef struct SDL_QuitEvent * the programmer; the only requirement is that '''type''' is a value obtained * from SDL_RegisterEvents(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_UserEvent { @@ -912,7 +978,10 @@ typedef struct SDL_UserEvent /** * The structure for all events in SDL. * - * \since This struct is available since SDL 3.0.0. + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. + * + * \since This struct is available since SDL 3.2.0. */ typedef union SDL_Event { @@ -951,6 +1020,7 @@ typedef union SDL_Event SDL_PenMotionEvent pmotion; /**< Pen motion event data */ SDL_PenButtonEvent pbutton; /**< Pen button event data */ SDL_PenAxisEvent paxis; /**< Pen axis event data */ + SDL_RenderEvent render; /**< Render event data */ SDL_DropEvent drop; /**< Drag and drop event data */ SDL_ClipboardEvent clipboard; /**< Clipboard event data */ @@ -981,10 +1051,6 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * * This function updates the event queue and internal input device state. * - * **WARNING**: This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider only doing those - * things on the main thread in any case. - * * SDL_PumpEvents() gathers all the pending input information from devices and * places it in the event queue. Without calls to SDL_PumpEvents() no events * would ever be placed on the queue. Often the need for calls to @@ -993,7 +1059,9 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * polling or waiting for events (e.g. you are filtering them), then you must * call SDL_PumpEvents() to force an event queue update. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent @@ -1001,11 +1069,17 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_EventAction { - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ } SDL_EventAction; /** @@ -1017,7 +1091,9 @@ typedef enum SDL_EventAction * event queue. * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. + * caller and will _not_ be removed from the queue. If you pass NULL for + * `events`, then `numevents` is ignored and the total number of matching + * events will be returned. * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the * caller and will be removed from the queue. @@ -1026,8 +1102,6 @@ typedef enum SDL_EventAction * Otherwise, the events may not be ready to be filtered when you call * SDL_PeepEvents(). * - * This function is thread-safe. - * * \param events destination buffer for the retrieved events, may be NULL to * leave the events in the queue and return the number of events * that would have been stored. @@ -1042,7 +1116,9 @@ typedef enum SDL_EventAction * \returns the number of events actually stored or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PumpEvents @@ -1058,14 +1134,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, * instead. * * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); /** @@ -1077,14 +1155,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); /** * Clear events of a specific type from the event queue. @@ -1106,7 +1186,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp * * \param type the type of event to be cleared; see SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvents */ @@ -1131,7 +1213,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * \param maxType the high end of event type to be cleared, inclusive; see * SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvent */ @@ -1171,16 +1255,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * * \param event the SDL_Event structure to be filled with the next event from * the queue, or NULL. - * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none - * available. + * \returns true if this got an event or false if there are none available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent * \sa SDL_WaitEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); /** * Wait indefinitely for the next available event. @@ -1193,16 +1278,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * * \param event the SDL_Event structure to be filled in with the next event * from the queue, or NULL. - * \returns SDL_TRUE on success or SDL_FALSE if there was an error while - * waiting for events; call SDL_GetError() for more information. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); /** * Wait until the specified timeout (in milliseconds) for the next available @@ -1221,16 +1308,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * from the queue, or NULL. * \param timeoutMS the maximum number of milliseconds to wait for the next * available event. - * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed - * without any events available. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEvent */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); /** * Add an event to the event queue. @@ -1244,8 +1333,6 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * Note: Pushing device input events onto the queue doesn't modify the state * of the device within SDL. * - * This function is thread-safe, and can be called from other threads safely. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter but events added with SDL_PeepEvents() do not. * @@ -1254,17 +1341,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * its own custom event types. * * \param event the SDL_Event to be added to the queue. - * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on - * failure; call SDL_GetError() for more information. A common reason - * for error is the event queue being full. + * \returns true on success, false if the event was filtered or on failure; + * call SDL_GetError() for more information. A common reason for + * error is the event queue being full. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PeepEvents * \sa SDL_PollEvent * \sa SDL_RegisterEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); /** * A function pointer used for callbacks that watch the event queue. @@ -1272,29 +1361,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * SDL_AddEventWatch, etc. * \param event the event that triggered the callback. - * \returns SDL_TRUE to permit event to be added to the queue, and SDL_FALSE - * to disallow it. When used with SDL_AddEventWatch, the return value - * is ignored. + * \returns true to permit event to be added to the queue, and false to + * disallow it. When used with SDL_AddEventWatch, the return value is + * ignored. * * \threadsafety SDL may call this callback at any time from any thread; the * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetEventFilter * \sa SDL_AddEventWatch */ -typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. * - * If the filter function returns SDL_TRUE when called, then the event will be - * added to the internal queue. If it returns SDL_FALSE, then the event will - * be dropped from the queue, but the internal state will still be updated. - * This allows selective filtering of dynamically arriving events. + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. + * + * If the filter function returns true when called, then the event will be + * added to the internal queue. If it returns false, then the event will be + * dropped from the queue, but the internal state will still be updated. This + * allows selective filtering of dynamically arriving events. * * **WARNING**: Be very careful of what you do in the event filter function, * as it may run in a different thread! @@ -1303,17 +1395,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. @@ -1321,11 +1405,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \threadsafety SDL may call the filter callback at any time from any thread; - * the application is responsible for locking resources the - * callback touches that need to be protected. + * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch * \sa SDL_SetEventEnabled @@ -1344,13 +1426,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void * \param filter the current callback function will be stored here. * \param userdata the pointer that is passed to the current event filter will * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. + * \returns true on success or false if there is no event filter set. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); /** * Add a callback to be triggered when an event is added to the event queue. @@ -1372,17 +1456,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, * * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); /** * Remove an event watch callback added with SDL_AddEventWatch(). @@ -1393,7 +1477,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, v * \param filter the function originally passed to SDL_AddEventWatch(). * \param userdata the pointer originally passed to SDL_AddEventWatch(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -1401,7 +1487,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo /** * Run a specific filter function on the current event queue, removing any - * events for which the filter returns SDL_FALSE. + * events for which the filter returns false. * * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), * this function does not change the filter permanently, it only uses the @@ -1410,7 +1496,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo * \param filter the SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetEventFilter * \sa SDL_SetEventFilter @@ -1423,23 +1511,27 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void * * \param type the type of event; see SDL_EventType for details. * \param enabled whether to process the event or not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EventEnabled */ -extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); /** * Query the state of processing events by type. * * \param type the type of event; see SDL_EventType for details. - * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. + * \returns true if the event is being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); /** * Allocate a set of user-defined events, and return the beginning event @@ -1449,7 +1541,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); * \returns the beginning event number, or 0 if numevents is invalid or if * there are not enough user-defined events left. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent */ @@ -1461,7 +1555,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); * \param event an event containing a `windowID`. * \returns the associated window on success or NULL if there is none. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_filesystem.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_filesystem.h index 5faa244..af3ca27 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_filesystem.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_filesystem.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,23 @@ /** * # CategoryFilesystem * - * SDL Filesystem API. + * SDL offers an API for examining and manipulating the system's filesystem. + * This covers most things one would need to do with directories, except for + * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) + * and [CategoryAsyncIO](CategoryAsyncIO) instead). + * + * There are functions to answer necessary path questions: + * + * - Where is my app's data? SDL_GetBasePath(). + * - Where can I safely write files? SDL_GetPrefPath(). + * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder(). + * - What is this thing at this location? SDL_GetPathInfo(). + * - What items live in this folder? SDL_EnumerateDirectory(). + * - What items live in this folder by wildcard? SDL_GlobDirectory(). + * - What is my current working directory? SDL_GetCurrentDirectory(). + * + * SDL also offers functions to manipulate the directory tree: renaming, + * removing, copying files. */ #ifndef SDL_filesystem_h_ @@ -73,7 +89,7 @@ extern "C" { * doesn't implement this functionality, call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrefPath */ @@ -128,7 +144,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); * etc.). This should be freed with SDL_free() when it is no longer * needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBasePath */ @@ -143,66 +159,40 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * * * The folders supported per platform are: * - * | | Windows | WinRT/UWP |macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | - * | ----------- | ------- | --------- |--------- | ---- | ---------- | ----- | ---------- | - * | HOME | X | X | X | | X | X | X | - * | DESKTOP | X | X | X | | X | X | | - * | DOCUMENTS | X | X | X | | X | | | - * | DOWNLOADS | Vista+ | X | X | | X | | | - * | MUSIC | X | X | X | | X | | | - * | PICTURES | X | X | X | | X | | | - * | PUBLICSHARE | | | X | | X | | | - * | SAVEDGAMES | Vista+ | | | | | | | - * | SCREENSHOTS | Vista+ | X | | | | | | - * | TEMPLATES | X | X | X | | X | | | - * | VIDEOS | X | X | X* | | X | | | + * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | + * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- | + * | HOME | X | X | | X | X | X | + * | DESKTOP | X | X | | X | X | | + * | DOCUMENTS | X | X | | X | | | + * | DOWNLOADS | Vista+ | X | | X | | | + * | MUSIC | X | X | | X | | | + * | PICTURES | X | X | | X | | | + * | PUBLICSHARE | | X | | X | | | + * | SAVEDGAMES | Vista+ | | | | | | + * | SCREENSHOTS | Vista+ | | | | | | + * | TEMPLATES | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | * * Note that on macOS/iOS, the Videos folder is called "Movies". * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetUserFolder */ typedef enum SDL_Folder { - /** The folder which contains all of the current user's data, preferences, - and documents. It usually contains most of the other folders. If a - requested folder does not exist, the home folder can be considered a safe - fallback to store a user's documents. */ - SDL_FOLDER_HOME, - /** The folder of files that are displayed on the desktop. Note that the - existence of a desktop folder does not guarantee that the system does - show icons on its desktop; certain GNU/Linux distros with a graphical - environment may not have desktop icons. */ - SDL_FOLDER_DESKTOP, - /** User document files, possibly application-specific. This is a good - place to save a user's projects. */ - SDL_FOLDER_DOCUMENTS, - /** Standard folder for user files downloaded from the internet. */ - SDL_FOLDER_DOWNLOADS, - /** Music files that can be played using a standard music player (mp3, - ogg...). */ - SDL_FOLDER_MUSIC, - /** Image files that can be displayed using a standard viewer (png, - jpg...). */ - SDL_FOLDER_PICTURES, - /** Files that are meant to be shared with other users on the same - computer. */ - SDL_FOLDER_PUBLICSHARE, - /** Save files for games. */ - SDL_FOLDER_SAVEDGAMES, - /** Application screenshots. */ - SDL_FOLDER_SCREENSHOTS, - /** Template files to be used when the user requests the desktop environment - to create a new file in a certain folder, such as "New Text File.txt". - Any file in the Templates folder can be used as a starting point for a - new file. */ - SDL_FOLDER_TEMPLATES, - /** Video files that can be played using a standard video player (mp4, - webm...). */ - SDL_FOLDER_VIDEOS, - /** total number of types in this enum, not a folder type by itself. */ - SDL_FOLDER_TOTAL + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ } SDL_Folder; /** @@ -226,13 +216,24 @@ typedef enum SDL_Folder * \returns either a null-terminated C string containing the full path to the * folder, or NULL if an error happened. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder); /* Abstract filesystem interface */ +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ typedef enum SDL_PathType { SDL_PATHTYPE_NONE, /**< path does not exist */ @@ -241,19 +242,27 @@ typedef enum SDL_PathType SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */ } SDL_PathType; +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ typedef struct SDL_PathInfo { - SDL_PathType type; /* the path type */ - Uint64 size; /* the file size in bytes */ - SDL_Time create_time; /* the time when the path was created */ - SDL_Time modify_time; /* the last time the path was modified */ - SDL_Time access_time; /* the last time the path was read */ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ } SDL_PathInfo; /** - * Flags for path matching + * Flags for path matching. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GlobDirectory * \sa SDL_GlobStorageDirectory @@ -263,73 +272,160 @@ typedef Uint32 SDL_GlobFlags; #define SDL_GLOB_CASEINSENSITIVE (1u << 0) /** - * Create a directory. + * Create a directory, and any missing parent directories. + * + * This reports success if `path` already exists as a directory. + * + * If parent directories are missing, it will also create them. Note that if + * this fails, it will not remove any parent directories it already made. * * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateDirectory(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); -/* Callback for directory enumeration. Return 1 to keep enumerating, - 0 to stop enumerating (no error), -1 to stop enumerating and - report an error. `dirname` is the directory being enumerated, - `fname` is the enumerated entry. */ -typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param dirname the directory that is being enumerated. + * \param fname the next entry in the enumeration. + * \returns how the enumeration should proceed. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); /** * Enumerate a directory through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. * * \param path the path of the directory to enumerate. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory. * - * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. * - * \since This function is available since SDL 3.0.0. + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemovePath(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); /** * Rename a file or directory. * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); /** * Copy a file. * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `newpath`'s previous contents will be gone, replaced with + * an incomplete copy of the data. To avoid this risk, it is recommended that + * the app copy to a temporary file in the same directory as `newpath`, and if + * the copy is successful, use SDL_RenamePath() to replace `newpath` with the + * temporary file. This will ensure that reads of `newpath` will either see a + * complete copy of the data, or it will see the pre-copy state of `newpath`. + * + * This function attempts to synchronize the newly-copied data to disk before + * returning, if the platform allows it, so that the renaming trick will not + * have a problem in a system crash or power failure, where the file could be + * renamed but the contents never made it from the system file cache to the + * physical disk. + * + * If the copy fails for any reason, the state of `newpath` is undefined. It + * might be half a copy, it might be the untouched data of what was already + * there, or it might be a zero-byte file, etc. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); /** * Get information about a filesystem path. @@ -337,21 +433,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const cha * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); /** * Enumerate a directory tree, filtered by pattern, and return a list. * * Files are filtered out if they don't match the string in `pattern`, which - * may contain wildcard characters '*' (match everything) and '?' (match one + * may contain wildcard characters '\*' (match everything) and '?' (match one * character). If pattern is NULL, no filtering is done and all results are * returned. Subdirectories are permitted, and are specified with a path - * separator of '/'. Wildcard characters '*' and '?' never match a path + * separator of '/'. Wildcard characters '\*' and '?' never match a path * separator. * * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching @@ -373,10 +469,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count); +/** + * Get what the system believes is the "current working directory." + * + * For systems without a concept of a current working directory, this will + * still attempt to provide something reasonable. + * + * SDL does not provide a means to _change_ the current working directory; for + * platforms without this concept, this would cause surprises with file access + * outside of SDL. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns a UTF-8 string of the current working directory in + * platform-dependent notation. NULL if there's a problem. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gamepad.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gamepad.h index 3d2d726..264f763 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gamepad.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gamepad.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,6 +51,24 @@ * If you would like to receive gamepad updates while the application is in * the background, you should set the following hint before calling * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. */ #ifndef SDL_gamepad_h_ @@ -58,9 +76,11 @@ #include #include -#include -#include +#include #include +#include +#include +#include #include #include @@ -72,7 +92,7 @@ extern "C" { /** * The structure used to identify an SDL gamepad * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Gamepad SDL_Gamepad; @@ -98,7 +118,7 @@ typedef enum SDL_GamepadType SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_GAMEPAD_TYPE_MAX + SDL_GAMEPAD_TYPE_COUNT } SDL_GamepadType; /** @@ -122,15 +142,15 @@ typedef enum SDL_GamepadType * You can query the labels for the face buttons using * SDL_GetGamepadButtonLabel() * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButton { SDL_GAMEPAD_BUTTON_INVALID = -1, - SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */ - SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */ - SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */ - SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */ + SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */ + SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */ + SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */ + SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */ SDL_GAMEPAD_BUTTON_BACK, SDL_GAMEPAD_BUTTON_GUIDE, SDL_GAMEPAD_BUTTON_START, @@ -142,18 +162,18 @@ typedef enum SDL_GamepadButton SDL_GAMEPAD_BUTTON_DPAD_DOWN, SDL_GAMEPAD_BUTTON_DPAD_LEFT, SDL_GAMEPAD_BUTTON_DPAD_RIGHT, - SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ - SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */ - SDL_GAMEPAD_BUTTON_MISC2, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC3, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC4, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC5, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC6, /* Additional button */ - SDL_GAMEPAD_BUTTON_MAX + SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */ + SDL_GAMEPAD_BUTTON_COUNT } SDL_GamepadButton; /** @@ -165,7 +185,7 @@ typedef enum SDL_GamepadButton * For a complete set, you should look at the button and gamepad type and have * a set of symbols that work well with your art style. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButtonLabel { @@ -192,7 +212,7 @@ typedef enum SDL_GamepadButtonLabel * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the * same range that will be reported by the lower-level SDL_GetJoystickAxis(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadAxis { @@ -203,7 +223,7 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_RIGHTY, SDL_GAMEPAD_AXIS_LEFT_TRIGGER, SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, - SDL_GAMEPAD_AXIS_MAX + SDL_GAMEPAD_AXIS_COUNT } SDL_GamepadAxis; /** @@ -214,7 +234,7 @@ typedef enum SDL_GamepadAxis * gamepad. This enum is used as part of SDL_GamepadBinding to specify those * mappings. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadBindingType { @@ -235,7 +255,7 @@ typedef enum SDL_GamepadBindingType * more with a simple text string. Those strings are parsed into a collection * of these structs to make it easier to operate on the data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetGamepadBindings */ @@ -293,6 +313,9 @@ typedef struct SDL_GamepadBinding * * Buttons can be used as a gamepad axes and vice versa. * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * * This string shows an example of a valid mapping for a gamepad: * * ```c @@ -305,10 +328,15 @@ typedef struct SDL_GamepadBinding * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); @@ -321,6 +349,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -330,21 +361,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * constrained environment. * * \param src the data stream for the mappings to be added. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the number of mappings added or -1 on failure; call SDL_GetError() * for more information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromFile * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ -extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); /** * Load a set of gamepad mappings from a file. @@ -355,6 +389,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -365,12 +402,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); @@ -379,12 +419,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file) * * This will generate gamepad events as needed if device mappings change. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. @@ -396,7 +436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); @@ -408,7 +448,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); * information. This should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUID @@ -425,7 +465,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid); * available; call SDL_GetError() for more information. This should * be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMappingForID @@ -442,26 +482,26 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); * \param instance_id the joystick instance ID. * \param mapping the mapping to use for this device, or NULL to clear the * mapping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMapping */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); /** * Return whether a gamepad is currently connected. * - * \returns SDL_TRUE if a gamepad is connected, SDL_FALSE otherwise. + * \returns true if a gamepad is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. @@ -472,7 +512,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasGamepad * \sa SDL_OpenGamepad @@ -483,15 +523,15 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); * Check if the given joystick is supported by the gamepad interface. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the given joystick is supported by the gamepad - * interface, SDL_FALSE if it isn't or it's an invalid index. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks * \sa SDL_OpenGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); /** * Get the implementation dependent name of a gamepad. @@ -502,7 +542,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); * \returns the name of the selected gamepad. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadName * \sa SDL_GetGamepads @@ -518,7 +558,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID * \returns the path of the selected gamepad. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPath * \sa SDL_GetGamepads @@ -533,7 +573,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepads @@ -549,7 +589,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID in * \returns the GUID of the selected gamepad. If called on an invalid index, * this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString * \sa SDL_GetGamepads @@ -566,7 +606,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID inst * \returns the USB vendor ID of the selected gamepad. If called on an invalid * index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendor * \sa SDL_GetGamepads @@ -583,7 +623,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID inst * \returns the USB product ID of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProduct * \sa SDL_GetGamepads @@ -600,7 +640,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID ins * \returns the product version of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersion * \sa SDL_GetGamepads @@ -615,7 +655,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_Joystic * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadType * \sa SDL_GetGamepads @@ -631,7 +671,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_Joystick * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepads @@ -648,7 +688,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys * \returns the mapping string. Returns NULL if no mapping is available. This * should be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads * \sa SDL_GetGamepadMapping @@ -662,7 +702,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID ins * \returns a gamepad identifier or NULL if an error occurred; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseGamepad * \sa SDL_IsGamepad @@ -677,7 +717,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instanc * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); @@ -687,7 +727,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID in * \param player_index the player index, which different from the instance ID. * \returns the SDL_Gamepad associated with a player index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_SetGamepadPlayerIndex @@ -717,7 +757,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int play * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); @@ -735,7 +775,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa * \returns the instance ID of the specified gamepad on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); @@ -747,7 +787,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad * \returns the implementation dependent name for the gamepad, or NULL if * there is no name or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadNameForID */ @@ -761,7 +801,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad * \returns the implementation dependent path for the gamepad, or NULL if * there is no path or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPathForID */ @@ -774,7 +814,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID */ @@ -787,7 +827,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRealGamepadTypeForID */ @@ -801,7 +841,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad * * \param gamepad the gamepad object to query. * \returns the player index for gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadPlayerIndex */ @@ -813,14 +853,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to adjust. * \param player_index player index to assign to this gamepad, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); /** * Get the USB vendor ID of an opened gamepad, if available. @@ -830,7 +870,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *game * \param gamepad the gamepad object to query. * \returns the USB vendor ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendorForID */ @@ -844,7 +884,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductForID */ @@ -858,7 +898,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersionForID */ @@ -872,7 +912,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gam * \param gamepad the gamepad object to query. * \returns the gamepad firmware version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); @@ -884,7 +924,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga * \param gamepad the gamepad object to query. * \returns the serial number, or NULL if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); @@ -897,7 +937,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamep * \param gamepad the gamepad object to query. * \returns the gamepad handle, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); @@ -909,7 +949,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepa * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); @@ -929,7 +969,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnection * battery. * \returns the current battery state. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); @@ -938,12 +978,12 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad * * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). - * \returns SDL_TRUE if the gamepad has been opened and is currently - * connected, or SDL_FALSE if not. + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** * Get the underlying joystick from a gamepad. @@ -961,7 +1001,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); @@ -973,12 +1013,12 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g * * \param enabled whether to process gamepad events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadEventsEnabled * \sa SDL_UpdateGamepads */ -extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); /** * Query the state of gamepad event processing. @@ -986,14 +1026,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * and check the state of the gamepad when you want gamepad information. * - * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE - * otherwise. + * \returns true if gamepad events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); /** * Get the SDL joystick layer bindings for a gamepad. @@ -1005,7 +1044,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); @@ -1016,7 +1055,7 @@ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gam * enabled. Under such circumstances, it will not be necessary to call this * function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); @@ -1032,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); * \returns the SDL_GamepadType enum corresponding to the input string, or * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForType */ @@ -1046,7 +1085,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeFromString */ @@ -1068,7 +1107,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_Gamepad * \returns the SDL_GamepadAxis enum corresponding to the input string, or * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForAxis */ @@ -1082,7 +1121,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAxisFromString */ @@ -1096,14 +1135,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad * * \param gamepad a gamepad. * \param axis an axis enum value (an SDL_GamepadAxis value). - * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. + * \returns true if the gamepad has this axis, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); /** * Get the current state of an axis control on a gamepad. @@ -1122,7 +1161,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD * \returns axis state (including 0) on success or 0 (also) on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis * \sa SDL_GetGamepadButton @@ -1141,7 +1180,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_ * \returns the SDL_GamepadButton enum corresponding to the input string, or * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForButton */ @@ -1155,7 +1194,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonFromString */ @@ -1169,28 +1208,27 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep * * \param gamepad a gamepad. * \param button a button enum value (an SDL_GamepadButton value). - * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. + * \returns true if the gamepad has this button, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the current state of a button on a gamepad. * * \param gamepad a gamepad. * \param button a button index (one of the SDL_GamepadButton values). - * \returns 1 for pressed state or 0 for not pressed state or failure; call - * SDL_GetError() for more information. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the label of a button on a gamepad. @@ -1199,7 +1237,7 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabel */ @@ -1212,7 +1250,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabelForType */ @@ -1224,7 +1262,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL * \param gamepad a gamepad. * \returns number of touchpads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ @@ -1238,7 +1276,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad) * \param touchpad a touchpad. * \returns number of supported simultaneous fingers. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTouchpadFinger * \sa SDL_GetNumGamepadTouchpads @@ -1251,35 +1289,36 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga * \param gamepad a gamepad. * \param touchpad a touchpad. * \param finger a finger. - * \param state filled with state. - * \param x filled with x position, normalized 0 to 1, with the origin in the - * upper left. - * \param y filled with y position, normalized 0 to 1, with the origin in the - * upper left. - * \param pressure filled with pressure value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); /** * Return whether a gamepad has a particular sensor. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. + * \returns true if the sensor exists, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadSensorData * \sa SDL_GetGamepadSensorDataRate * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Set whether data reporting for a gamepad sensor is enabled. @@ -1287,28 +1326,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, * \param gamepad the gamepad to update. * \param type the type of sensor to enable/disable. * \param enabled whether data reporting should be enabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasSensor * \sa SDL_GamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); /** * Query whether sensor data reporting is enabled for a gamepad. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. + * \returns true if the sensor is enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Get the data rate (number of events per second) of a gamepad sensor. @@ -1317,7 +1356,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep * \param type the type of sensor to query. * \returns the data rate, or 0.0f if the data rate is not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); @@ -1331,12 +1370,12 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game * \param type the type of sensor to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); /** * Start a rumble effect on a gamepad. @@ -1353,12 +1392,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamep * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the gamepad's triggers. @@ -1379,14 +1418,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uin * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a gamepad's LED color. @@ -1401,12 +1440,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *game * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** * Send a gamepad specific effect packet. @@ -1414,12 +1453,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uin * \param gamepad the gamepad to affect. * \param data the data to send to the gamepad. * \param size the size of the data to send to the gamepad. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); /** * Close a gamepad previously opened with SDL_OpenGamepad(). @@ -1427,7 +1466,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenGamepad */ @@ -1441,7 +1480,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); * \param button a button on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis */ @@ -1454,7 +1493,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt * \param axis an axis on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForButton */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gpu.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gpu.h index bba47cc..fa870a5 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gpu.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_gpu.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,281 @@ /** * # CategoryGPU * - * Include file for SDL GPU API functions + * The GPU API offers a cross-platform way for apps to talk to modern graphics + * hardware. It offers both 3D graphics and compute support, in the style of + * Metal, Vulkan, and Direct3D 12. + * + * A basic workflow might be something like this: + * + * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to + * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you + * can render offscreen entirely, perhaps for image processing, and not use a + * window at all. + * + * Next the app prepares static data (things that are created once and used + * over and over). For example: + * + * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader(). + * - Vertex buffers (arrays of geometry data) and other data rendering will + * need: use SDL_UploadToGPUBuffer(). + * - Textures (images): use SDL_UploadToGPUTexture(). + * - Samplers (how textures should be read from): use SDL_CreateGPUSampler(). + * - Render pipelines (precalculated rendering state): use + * SDL_CreateGPUGraphicsPipeline() + * + * To render, the app creates one or more command buffers, with + * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering + * instructions that will be submitted to the GPU in batch. Complex scenes can + * use multiple command buffers, maybe configured across multiple threads in + * parallel, as long as they are submitted in the correct order, but many apps + * will just need one command buffer per frame. + * + * Rendering can happen to a texture (what other APIs call a "render target") + * or it can happen to the swapchain texture (which is just a special texture + * that represents a window's contents). The app can use + * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. */ #ifndef SDL_gpu_h_ @@ -44,132 +318,394 @@ extern "C" { /* Type Declarations */ +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ typedef struct SDL_GPUFence SDL_GPUFence; +/** + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUPrimitiveType { - SDL_GPU_PRIMITIVETYPE_POINTLIST, - SDL_GPU_PRIMITIVETYPE_LINELIST, - SDL_GPU_PRIMITIVETYPE_LINESTRIP, - SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, - SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ } SDL_GPUPrimitiveType; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPULoadOp { - SDL_GPU_LOADOP_LOAD, - SDL_GPU_LOADOP_CLEAR, - SDL_GPU_LOADOP_DONT_CARE + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ } SDL_GPULoadOp; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPUStoreOp { - SDL_GPU_STOREOP_STORE, - SDL_GPU_STOREOP_DONT_CARE + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ } SDL_GPUStoreOp; +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUIndexElementSize { - SDL_GPU_INDEXELEMENTSIZE_16BIT, - SDL_GPU_INDEXELEMENTSIZE_32BIT + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ } SDL_GPUIndexElementSize; -/* Texture format support varies depending on driver, hardware, and usage flags. - * In general, you should use SDL_GPUTextureSupportsFormat to query if a format - * is supported before using it. However, there are a few guaranteed formats. +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE * * For SAMPLER usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R8G8_SNORM - * - R8G8B8A8_SNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB - * - D16_UNORM + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM * * For COLOR_TARGET usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB * * For STORAGE usages, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - R8G8B8A8_SNORM - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT * - * For DEPTH_STENCIL_TARGET usage, the following formats are universally supported: - * - D16_UNORM - * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT - * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT * - * Unless D16_UNORM is sufficient for your purposes, always check which - * of D24/D32 is supported before creating a depth-stencil texture! + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat */ typedef enum SDL_GPUTextureFormat { - SDL_GPU_TEXTUREFORMAT_INVALID = -1, + SDL_GPU_TEXTUREFORMAT_INVALID, /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, - SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, - SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, - SDL_GPU_TEXTUREFORMAT_R8_UNORM, - SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, /* Compressed Unsigned Normalized Float Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC1_UNORM, - SDL_GPU_TEXTUREFORMAT_BC2_UNORM, - SDL_GPU_TEXTUREFORMAT_BC3_UNORM, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, /* Signed Float Color Formats */ SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, @@ -177,6 +713,8 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, /* Unsigned Integer Color Formats */ SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_UINT, @@ -184,48 +722,153 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, /* SRGB Unsigned Normalized Color Formats */ SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, /* Compressed SRGB Unsigned Normalized Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC3_UNORM_SRGB, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, /* Depth Formats */ SDL_GPU_TEXTUREFORMAT_D16_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D32_FLOAT, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, - SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT } SDL_GPUTextureFormat; -typedef enum SDL_GPUTextureUsageFlagBits -{ - SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT = 0x00000001, - SDL_GPU_TEXTUREUSAGE_COLOR_TARGET_BIT = 0x00000002, - SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET_BIT = 0x00000004, - SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUTextureUsageFlagBits; - +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef Uint32 SDL_GPUTextureUsageFlags; +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef enum SDL_GPUTextureType { - SDL_GPU_TEXTURETYPE_2D, - SDL_GPU_TEXTURETYPE_2D_ARRAY, - SDL_GPU_TEXTURETYPE_3D, - SDL_GPU_TEXTURETYPE_CUBE + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ } SDL_GPUTextureType; +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ typedef enum SDL_GPUSampleCount { - SDL_GPU_SAMPLECOUNT_1, - SDL_GPU_SAMPLECOUNT_2, - SDL_GPU_SAMPLECOUNT_4, - SDL_GPU_SAMPLECOUNT_8 + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ } SDL_GPUSampleCount; + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_GPUCubeMapFace { SDL_GPU_CUBEMAPFACE_POSITIVEX, @@ -236,45 +879,87 @@ typedef enum SDL_GPUCubeMapFace SDL_GPU_CUBEMAPFACE_NEGATIVEZ } SDL_GPUCubeMapFace; -typedef enum SDL_GPUBufferUsageFlagBits -{ - SDL_GPU_BUFFERUSAGE_VERTEX_BIT = 0x00000001, - SDL_GPU_BUFFERUSAGE_INDEX_BIT = 0x00000002, - SDL_GPU_BUFFERUSAGE_INDIRECT_BIT = 0x00000004, - SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUBufferUsageFlagBits; - +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ typedef Uint32 SDL_GPUBufferUsageFlags; +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef enum SDL_GPUTransferBufferUsage { SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD } SDL_GPUTransferBufferUsage; +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef enum SDL_GPUShaderStage { SDL_GPU_SHADERSTAGE_VERTEX, SDL_GPU_SHADERSTAGE_FRAGMENT } SDL_GPUShaderStage; -typedef enum SDL_GPUShaderFormatFlagBits -{ - SDL_GPU_SHADERFORMAT_INVALID = 0x00000000, - SDL_GPU_SHADERFORMAT_SECRET = 0x00000001, /* NDA'd platforms */ - SDL_GPU_SHADERFORMAT_SPIRV = 0x00000002, /* Vulkan */ - SDL_GPU_SHADERFORMAT_DXBC = 0x00000004, /* D3D11 (Shader Model 5_0) */ - SDL_GPU_SHADERFORMAT_DXIL = 0x00000008, /* D3D12 */ - SDL_GPU_SHADERFORMAT_MSL = 0x00000010, /* Metal */ - SDL_GPU_SHADERFORMAT_METALLIB = 0x00000020, /* Metal */ -} SDL_GPUShaderFormatFlagBits; - +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef Uint32 SDL_GPUShaderFormat; +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexElementFormat { + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + /* 32-bit Signed Integers */ SDL_GPU_VERTEXELEMENTFORMAT_INT, SDL_GPU_VERTEXELEMENTFORMAT_INT2, @@ -330,125 +1015,230 @@ typedef enum SDL_GPUVertexElementFormat SDL_GPU_VERTEXELEMENTFORMAT_HALF4 } SDL_GPUVertexElementFormat; +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexInputRate { - SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, - SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ } SDL_GPUVertexInputRate; +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFillMode { - SDL_GPU_FILLMODE_FILL, - SDL_GPU_FILLMODE_LINE + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ } SDL_GPUFillMode; +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCullMode { - SDL_GPU_CULLMODE_NONE, - SDL_GPU_CULLMODE_FRONT, - SDL_GPU_CULLMODE_BACK + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ } SDL_GPUCullMode; +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFrontFace { - SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, - SDL_GPU_FRONTFACE_CLOCKWISE + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ } SDL_GPUFrontFace; +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCompareOp { - SDL_GPU_COMPAREOP_NEVER, - SDL_GPU_COMPAREOP_LESS, - SDL_GPU_COMPAREOP_EQUAL, - SDL_GPU_COMPAREOP_LESS_OR_EQUAL, - SDL_GPU_COMPAREOP_GREATER, - SDL_GPU_COMPAREOP_NOT_EQUAL, - SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, - SDL_GPU_COMPAREOP_ALWAYS + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ } SDL_GPUCompareOp; +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUStencilOp { - SDL_GPU_STENCILOP_KEEP, - SDL_GPU_STENCILOP_ZERO, - SDL_GPU_STENCILOP_REPLACE, - SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_INVERT, - SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, - SDL_GPU_STENCILOP_DECREMENT_AND_WRAP + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ } SDL_GPUStencilOp; +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendOp { - SDL_GPU_BLENDOP_ADD, - SDL_GPU_BLENDOP_SUBTRACT, - SDL_GPU_BLENDOP_REVERSE_SUBTRACT, - SDL_GPU_BLENDOP_MIN, - SDL_GPU_BLENDOP_MAX + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ } SDL_GPUBlendOp; +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendFactor { - SDL_GPU_BLENDFACTOR_ZERO, - SDL_GPU_BLENDFACTOR_ONE, - SDL_GPU_BLENDFACTOR_SRC_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, - SDL_GPU_BLENDFACTOR_DST_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_DST_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, - SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ } SDL_GPUBlendFactor; -typedef enum SDL_GPUColorComponentFlagBits -{ - SDL_GPU_COLORCOMPONENT_R_BIT = 0x00000001, - SDL_GPU_COLORCOMPONENT_G_BIT = 0x00000002, - SDL_GPU_COLORCOMPONENT_B_BIT = 0x00000004, - SDL_GPU_COLORCOMPONENT_A_BIT = 0x00000008 -} SDL_GPUColorComponentFlagBits; - +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef Uint8 SDL_GPUColorComponentFlags; +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUFilter { - SDL_GPU_FILTER_NEAREST, - SDL_GPU_FILTER_LINEAR + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ } SDL_GPUFilter; +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerMipmapMode { - SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, - SDL_GPU_SAMPLERMIPMAPMODE_LINEAR + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ } SDL_GPUSamplerMipmapMode; +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerAddressMode { - SDL_GPU_SAMPLERADDRESSMODE_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ } SDL_GPUSamplerAddressMode; -/* - * VSYNC: - * Waits for vblank before presenting. - * If there is a pending image to present, the new image is enqueued for presentation. - * Disallows tearing at the cost of visual latency. - * When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight. - * IMMEDIATE: - * Immediately presents. - * Lowest latency option, but tearing may occur. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. - * MAILBOX: - * Waits for vblank before presenting. No tearing is possible. - * If there is a pending image to present, the pending image is replaced by the new image. - * Similar to VSYNC, but with reduced visual latency. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUPresentMode { @@ -457,493 +1247,866 @@ typedef enum SDL_GPUPresentMode SDL_GPU_PRESENTMODE_MAILBOX } SDL_GPUPresentMode; -/* - * SDR: - * B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. Blends raw pixel values. - * SDR_LINEAR: - * B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. Blends in linear space. - * HDR_EXTENDED_LINEAR: - * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. Blends in linear space. - * HDR10_ST2048: - * A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding. Blends raw pixel values. (TODO: verify this) +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUSwapchainComposition { SDL_GPU_SWAPCHAINCOMPOSITION_SDR, SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, - SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 } SDL_GPUSwapchainComposition; -typedef enum SDL_GPUDriver -{ - SDL_GPU_DRIVER_INVALID = -1, - SDL_GPU_DRIVER_SECRET, /* NDA'd platforms */ - SDL_GPU_DRIVER_VULKAN, - SDL_GPU_DRIVER_D3D11, - SDL_GPU_DRIVER_D3D12, - SDL_GPU_DRIVER_METAL -} SDL_GPUDriver; - /* Structures */ -typedef struct SDL_GPUDepthStencilValue -{ - float depth; - Uint8 stencil; -} SDL_GPUDepthStencilValue; - +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ typedef struct SDL_GPUViewport { - float x; - float y; - float w; - float h; - float minDepth; - float maxDepth; + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ } SDL_GPUViewport; +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureTransferInfo { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; /* starting location of the image data */ - Uint32 imagePitch; /* number of pixels from one row to the next */ - Uint32 imageHeight; /* number of rows from one layer/depth-slice to the next */ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ } SDL_GPUTextureTransferInfo; +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUTransferBufferLocation { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ } SDL_GPUTransferBufferLocation; +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + */ typedef struct SDL_GPUTextureLocation { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ } SDL_GPUTextureLocation; +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; - Uint32 w; - Uint32 h; - Uint32 d; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ } SDL_GPUTextureRegion; +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ typedef struct SDL_GPUBlitRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; - Uint32 x; - Uint32 y; - Uint32 w; - Uint32 h; + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ } SDL_GPUBlitRegion; +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + */ typedef struct SDL_GPUBufferLocation { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ } SDL_GPUBufferLocation; +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUBufferRegion { - SDL_GPUBuffer *buffer; - Uint32 offset; - Uint32 size; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ } SDL_GPUBufferRegion; -/* Note that the `firstVertex` and `firstInstance` parameters are NOT compatible with - * built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If - * your shader depends on these variables, the correlating draw call parameter MUST - * be 0. +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect */ typedef struct SDL_GPUIndirectDrawCommand { - Uint32 vertexCount; /* number of vertices to draw */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstVertex; /* index of the first vertex to draw */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ typedef struct SDL_GPUIndexedIndirectDrawCommand { - Uint32 indexCount; /* number of vertices to draw per instance */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstIndex; /* base index within the index buffer */ - Sint32 vertexOffset; /* value added to vertex index before indexing into the vertex buffer */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndexedIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ typedef struct SDL_GPUIndirectDispatchCommand { - Uint32 groupCountX; - Uint32 groupCountY; - Uint32 groupCountZ; + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ } SDL_GPUIndirectDispatchCommand; /* State structures */ +/** + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef struct SDL_GPUSamplerCreateInfo { - SDL_GPUFilter minFilter; - SDL_GPUFilter magFilter; - SDL_GPUSamplerMipmapMode mipmapMode; - SDL_GPUSamplerAddressMode addressModeU; - SDL_GPUSamplerAddressMode addressModeV; - SDL_GPUSamplerAddressMode addressModeW; - float mipLodBias; - SDL_bool anisotropyEnable; - float maxAnisotropy; - SDL_bool compareEnable; - SDL_GPUCompareOp compareOp; - float minLod; - float maxLod; + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUSamplerCreateInfo; -typedef struct SDL_GPUVertexBinding +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexBufferDescription { - Uint32 binding; - Uint32 stride; - SDL_GPUVertexInputRate inputRate; - Uint32 instanceStepRate; /* ignored unless inputRate is INSTANCE */ -} SDL_GPUVertexBinding; + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */ +} SDL_GPUVertexBufferDescription; +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + */ typedef struct SDL_GPUVertexAttribute { - Uint32 location; - Uint32 binding; - SDL_GPUVertexElementFormat format; - Uint32 offset; + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ } SDL_GPUVertexAttribute; +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + */ typedef struct SDL_GPUVertexInputState { - const SDL_GPUVertexBinding *vertexBindings; - Uint32 vertexBindingCount; - const SDL_GPUVertexAttribute *vertexAttributes; - Uint32 vertexAttributeCount; + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ } SDL_GPUVertexInputState; +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ typedef struct SDL_GPUStencilOpState { - SDL_GPUStencilOp failOp; - SDL_GPUStencilOp passOp; - SDL_GPUStencilOp depthFailOp; - SDL_GPUCompareOp compareOp; + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ } SDL_GPUStencilOpState; -typedef struct SDL_GPUColorAttachmentBlendState +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState { - SDL_bool blendEnable; - SDL_GPUBlendFactor srcColorBlendFactor; - SDL_GPUBlendFactor dstColorBlendFactor; - SDL_GPUBlendOp colorBlendOp; - SDL_GPUBlendFactor srcAlphaBlendFactor; - SDL_GPUBlendFactor dstAlphaBlendFactor; - SDL_GPUBlendOp alphaBlendOp; - SDL_GPUColorComponentFlags colorWriteMask; -} SDL_GPUColorAttachmentBlendState; + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef struct SDL_GPUShaderCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - SDL_GPUShaderStage stage; - Uint32 samplerCount; - Uint32 storageTextureCount; - Uint32 storageBufferCount; - Uint32 uniformBufferCount; + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUShaderCreateInfo; +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + */ typedef struct SDL_GPUTextureCreateInfo { - SDL_GPUTextureType type; - SDL_GPUTextureFormat format; - SDL_GPUTextureUsageFlags usageFlags; - Uint32 width; - Uint32 height; - Uint32 layerCountOrDepth; - Uint32 levelCount; - SDL_GPUSampleCount sampleCount; + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTextureCreateInfo; -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" - +/** + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + */ typedef struct SDL_GPUBufferCreateInfo { - SDL_GPUBufferUsageFlags usageFlags; - Uint32 sizeInBytes; + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUBufferCreateInfo; +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef struct SDL_GPUTransferBufferCreateInfo { - SDL_GPUTransferBufferUsage usage; - Uint32 sizeInBytes; + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTransferBufferCreateInfo; /* Pipeline state structures */ +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if + * enable_depth_clip is true. If you rely on this clamp+clip behavior, + * consider enabling depth clip and then manually clamping depth in your + * fragment shaders on Metal and Vulkan. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPURasterizerState { - SDL_GPUFillMode fillMode; - SDL_GPUCullMode cullMode; - SDL_GPUFrontFace frontFace; - SDL_bool depthBiasEnable; - float depthBiasConstantFactor; - float depthBiasClamp; - float depthBiasSlopeFactor; + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; } SDL_GPURasterizerState; +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUMultisampleState { - SDL_GPUSampleCount sampleCount; - Uint32 sampleMask; + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */ + bool enable_mask; /**< Enables sample masking. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUMultisampleState; +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUDepthStencilState { - SDL_bool depthTestEnable; - SDL_bool depthWriteEnable; - SDL_GPUCompareOp compareOp; - SDL_bool stencilTestEnable; - SDL_GPUStencilOpState backStencilState; - SDL_GPUStencilOpState frontStencilState; - Uint8 compareMask; - Uint8 writeMask; - Uint8 reference; + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUDepthStencilState; -typedef struct SDL_GPUColorAttachmentDescription +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription { - SDL_GPUTextureFormat format; - SDL_GPUColorAttachmentBlendState blendState; -} SDL_GPUColorAttachmentDescription; + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; -typedef struct SDL_GPUGraphicsPipelineAttachmentInfo +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo { - SDL_GPUColorAttachmentDescription *colorAttachmentDescriptions; - Uint32 colorAttachmentCount; - SDL_bool hasDepthStencilAttachment; - SDL_GPUTextureFormat depthStencilFormat; -} SDL_GPUGraphicsPipelineAttachmentInfo; + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ typedef struct SDL_GPUGraphicsPipelineCreateInfo { - SDL_GPUShader *vertexShader; - SDL_GPUShader *fragmentShader; - SDL_GPUVertexInputState vertexInputState; - SDL_GPUPrimitiveType primitiveType; - SDL_GPURasterizerState rasterizerState; - SDL_GPUMultisampleState multisampleState; - SDL_GPUDepthStencilState depthStencilState; - SDL_GPUGraphicsPipelineAttachmentInfo attachmentInfo; - float blendConstants[4]; + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUGraphicsPipelineCreateInfo; +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + */ typedef struct SDL_GPUComputePipelineCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - Uint32 readOnlyStorageTextureCount; - Uint32 readOnlyStorageBufferCount; - Uint32 writeOnlyStorageTextureCount; - Uint32 writeOnlyStorageBufferCount; - Uint32 uniformBufferCount; - Uint32 threadCountX; - Uint32 threadCountY; - Uint32 threadCountZ; + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUComputePipelineCreateInfo; -typedef struct SDL_GPUColorAttachmentInfo +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo { - /* The texture that will be used as a color attachment by a render pass. */ - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; /* For 3D textures, you can bind an individual depth plane as an attachment. */ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; - /* Can be ignored by RenderPass if CLEAR is not used */ - SDL_FColor clearColor; - - /* Determines what is done with the texture at the beginning of the render pass. - * - * LOAD: - * Loads the data currently in the texture. - * - * CLEAR: - * Clears the texture to a single color. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the texture at the end of the render pass. - * - * STORE: - * Stores the results of the render pass in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and loadOp is not LOAD */ - SDL_bool cycle; -} SDL_GPUColorAttachmentInfo; - -typedef struct SDL_GPUDepthStencilAttachmentInfo +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo { - /* The texture that will be used as the depth stencil attachment by a render pass. */ - SDL_GPUTexture *texture; + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; - /* Can be ignored by the render pass if CLEAR is not used */ - SDL_GPUDepthStencilValue depthStencilClearValue; - - /* Determines what is done with the depth values at the beginning of the render pass. - * - * LOAD: - * Loads the depth values currently in the texture. - * - * CLEAR: - * Clears the texture to a single depth. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the depth values at the end of the render pass. - * - * STORE: - * Stores the depth results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* Determines what is done with the stencil values at the beginning of the render pass. - * - * LOAD: - * Loads the stencil values currently in the texture. - * - * CLEAR: - * Clears the texture to a single stencil value. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp stencilLoadOp; - - /* Determines what is done with the stencil values at the end of the render pass. - * - * STORE: - * Stores the stencil results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp stencilStoreOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and any load ops are not LOAD */ - SDL_bool cycle; -} SDL_GPUDepthStencilAttachmentInfo; +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; /* Binding structs */ +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + */ typedef struct SDL_GPUBufferBinding { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ } SDL_GPUBufferBinding; +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ typedef struct SDL_GPUTextureSamplerBinding { - SDL_GPUTexture *texture; - SDL_GPUSampler *sampler; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ } SDL_GPUTextureSamplerBinding; -typedef struct SDL_GPUStorageBufferWriteOnlyBinding +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding { - SDL_GPUBuffer *buffer; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; - /* if SDL_TRUE, cycles the buffer if it is bound. */ - SDL_bool cycle; -} SDL_GPUStorageBufferWriteOnlyBinding; - -typedef struct SDL_GPUStorageTextureWriteOnlyBinding +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - - /* if SDL_TRUE, cycles the texture if the texture is bound. */ - SDL_bool cycle; -} SDL_GPUStorageTextureWriteOnlyBinding; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; /* Functions */ /* Device */ /** - * Creates a GPU context. + * Checks for GPU runtime support. * - * \param formatFlags a bitflag indicating which shader formats the app is - * able to provide. - * \param debugMode enable debug mode properties and validations. + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. * \param name the preferred GPU driver, or NULL to let SDL pick the optimal * driver. - * \returns a GPU context on success or NULL on failure. + * \returns true if supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( - SDL_GPUShaderFormat formatFlags, - SDL_bool debugMode, + SDL_GPUShaderFormat format_flags, + bool debug_mode, const char *name); /** @@ -951,26 +2114,26 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * * These are the supported properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL`: enable debug mode properties - * and validations, defaults to SDL_TRUE. - * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL`: enable to prefer energy - * efficiency over maximum GPU performance, defaults to SDL_FALSE. + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to * use, if a specific one is desired. * * These are the current shader format properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to * provide shaders for an NDA platform. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to * provide SPIR-V shaders if applicable. - * - SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL`: The app is able to provide - * DXBC shaders if applicable - * `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to * provide DXIL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL`: The app is able to provide - * MSL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to * provide Metal shader libraries if applicable. * * With the D3D12 renderer: @@ -979,25 +2142,28 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * use for all vertex semantics, default is "TEXCOORD". * * \param props the properties to use. - * \returns a GPU context on success or NULL on failure. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( SDL_PropertiesID props); -#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" -#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL "SDL.gpu.device.create.shaders.secret" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" /** @@ -1005,70 +2171,132 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( * * \param device a GPU Context to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUDevice */ extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); /** - * Returns the backend used to create this GPU context. + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. * * \param device a GPU context to query. - * \returns an SDL_GPUDriver value, or SDL_GPU_DRIVER_INVALID on error. + * \returns the name of the device's driver, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); /* State Creation */ /** * Creates a pipeline object to be used in a compute workflow. * - * Shader resource bindings must be authored to follow a particular order. For - * SPIR-V shaders, use the following resource sets: 0: Read-only storage - * textures, followed by read-only storage buffers 1: Write-only storage - * textures, followed by write-only storage buffers 2: Uniform buffers + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Read-only storage textures, followed by read-only storage - * buffers For u registers: Write-only storage textures, followed by - * write-only storage buffers For b registers: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXIL shaders, use the following register order: (t[n], space0): - * Read-only storage textures, followed by read-only storage buffers (u[n], - * space1): Write-only storage textures, followed by write-only storage - * buffers (b[n], space2): Uniform buffers + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers * - * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, - * followed by write-only storage buffers, followed by write-only storage - * buffers For [[texture]]: Read-only storage textures, followed by write-only - * storage textures + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. * * \param device a GPU Context. - * \param computePipelineCreateInfo a struct describing the state of the - * requested compute pipeline. - * \returns a compute pipeline object on success, or NULL on failure. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUComputePipeline * \sa SDL_ReleaseGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipelineCreateInfo *computePipelineCreateInfo); + const SDL_GPUComputePipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" /** * Creates a pipeline object to be used in a graphics workflow. * - * \param device a GPU Context. - * \param pipelineCreateInfo a struct describing the state of the desired - * graphics pipeline. - * \returns a graphics pipeline object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUShader * \sa SDL_BindGPUGraphicsPipeline @@ -1076,26 +2304,36 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipelineCreateInfo *pipelineCreateInfo); + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" /** * Creates a sampler object to be used when binding textures in a graphics * workflow. * - * \param device a GPU Context. - * \param samplerCreateInfo a struct describing the state of the desired - * sampler. - * \returns a sampler object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUVertexSamplers * \sa SDL_BindGPUFragmentSamplers - * \sa SDL_ReleaseSampler + * \sa SDL_ReleaseGPUSampler */ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( SDL_GPUDevice *device, - SDL_GPUSamplerCreateInfo *samplerCreateInfo); + const SDL_GPUSamplerCreateInfo *createinfo); + +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" /** * Creates a shader to be used when creating a graphics pipeline. @@ -1103,46 +2341,78 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * Shader resource bindings must be authored to follow a particular order * depending on the shader format. * - * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: - * Sampled textures, followed by storage textures, followed by storage buffers - * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by - * storage textures, followed by storage buffers 3: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Sampled textures, followed by storage textures, followed by - * storage buffers For s registers: Samplers with indices corresponding to the - * sampled textures For b registers: Uniform buffers + * For vertex shaders: * - * For DXIL shaders, use the following register order: For vertex shaders: - * (t[n], space0): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space0): Samplers with indices corresponding to the - * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n], - * space2): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space2): Samplers with indices corresponding to the - * sampled textures (b[n], space3): Uniform buffers + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers * - * For MSL/metallib, use the following order: For [[texture]]: Sampled - * textures, followed by storage textures For [[sampler]]: Samplers with - * indices corresponding to the sampled textures For [[buffer]]: Uniform - * buffers, followed by storage buffers. Vertex buffer 0 is bound at - * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than - * manually authoring vertex buffer indices, use the [[stage_in]] attribute - * which will automatically use the vertex input information from the - * SDL_GPUPipeline. + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. * * \param device a GPU Context. - * \param shaderCreateInfo a struct describing the state of the desired - * shader. - * \returns a shader object on success, or NULL on failure. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUGraphicsPipeline * \sa SDL_ReleaseGPUShader */ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( SDL_GPUDevice *device, - SDL_GPUShaderCreateInfo *shaderCreateInfo); + const SDL_GPUShaderCreateInfo *createinfo); + +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" /** * Creates a texture object to be used in graphics or compute workflows. @@ -1157,12 +2427,36 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * - * \param device a GPU Context. - * \param textureCreateInfo a struct describing the state of the texture to - * create. - * \returns a texture object on success, or NULL on failure. + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the texture to create. + * \returns a texture object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture * \sa SDL_DownloadFromGPUTexture @@ -1177,7 +2471,15 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( */ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, - SDL_GPUTextureCreateInfo *textureCreateInfo); + const SDL_GPUTextureCreateInfo *createinfo); + +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" /** * Creates a buffer object to be used in graphics or compute workflows. @@ -1188,35 +2490,63 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * Note that certain combinations of usage flags are invalid. For example, a * buffer cannot have both the VERTEX and INDEX flags. * - * \param device a GPU Context. - * \param bufferCreateInfo a struct describing the state of the buffer to - * create. - * \returns a buffer object on success, or NULL on failure. + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer * \sa SDL_BindGPUVertexBuffers * \sa SDL_BindGPUIndexBuffer * \sa SDL_BindGPUVertexStorageBuffers * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect * \sa SDL_ReleaseGPUBuffer */ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( SDL_GPUDevice *device, - SDL_GPUBufferCreateInfo *bufferCreateInfo); + const SDL_GPUBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" /** * Creates a transfer buffer to be used when uploading to or downloading from * graphics resources. * - * \param device a GPU Context. - * \param transferBufferCreateInfo a struct describing the state of the - * transfer buffer to create. - * \returns a transfer buffer on success, or NULL on failure. + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer @@ -1226,20 +2556,28 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( */ extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBufferCreateInfo *transferBufferCreateInfo); + const SDL_GPUTransferBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" /* Debug Naming */ /** * Sets an arbitrary string constant to label a buffer. * - * Useful for debugging. + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. * * \param device a GPU Context. * \param buffer a buffer to attach the name to. * \param text a UTF-8 string constant to mark as the name of the buffer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( SDL_GPUDevice *device, @@ -1249,13 +2587,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( /** * Sets an arbitrary string constant to label a texture. * - * Useful for debugging. + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. * * \param device a GPU Context. * \param texture a texture to attach the name to. * \param text a UTF-8 string constant to mark as the name of the texture. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( SDL_GPUDevice *device, @@ -1267,13 +2612,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( * * Useful for debugging. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param text a UTF-8 string constant to insert as the label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *text); /** @@ -1290,28 +2635,28 @@ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( * pass rather than the command buffer. For best results, if you push a debug * group during a pass, always pop it in the same pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param name a UTF-8 string constant that names the group. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PopGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *name); /** * Ends the most-recently pushed debug group. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /* Disposal */ @@ -1323,7 +2668,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( * \param device a GPU context. * \param texture a texture to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( SDL_GPUDevice *device, @@ -1332,12 +2677,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( /** * Frees the given sampler as soon as it is safe to do so. * - * You must not reference the texture after calling this function. + * You must not reference the sampler after calling this function. * * \param device a GPU context. * \param sampler a sampler to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( SDL_GPUDevice *device, @@ -1351,7 +2696,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( * \param device a GPU context. * \param buffer a buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( SDL_GPUDevice *device, @@ -1363,13 +2708,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( * You must not reference the transfer buffer after calling this function. * * \param device a GPU context. - * \param transferBuffer a transfer buffer to be destroyed. + * \param transfer_buffer a transfer buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /** * Frees the given compute pipeline as soon as it is safe to do so. @@ -1377,13 +2722,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( * You must not reference the compute pipeline after calling this function. * * \param device a GPU context. - * \param computePipeline a compute pipeline to be destroyed. + * \param compute_pipeline a compute pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePipeline *compute_pipeline); /** * Frees the given shader as soon as it is safe to do so. @@ -1393,7 +2738,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( * \param device a GPU context. * \param shader a shader to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( SDL_GPUDevice *device, @@ -1405,29 +2750,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( * You must not reference the graphics pipeline after calling this function. * * \param device a GPU context. - * \param graphicsPipeline a graphics pipeline to be destroyed. + * \param graphics_pipeline a graphics pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipeline *graphicsPipeline); - -/* - * COMMAND BUFFERS - * - * Render state is managed via command buffers. - * When setting render state, that state is always local to the command buffer. - * - * Commands only begin execution on the GPU once Submit is called. - * Once the command buffer is submitted, it is no longer valid to use it. - * - * Command buffers are executed in submission order. If you submit command buffer A and then command buffer B - * all commands in A will begin executing before any command in B begins executing. - * - * In multi-threading scenarios, you should acquire and submit a command buffer on the same thread. - * As long as you satisfy this requirement, all functionality related to command buffers is thread-safe. - */ + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Acquire a command buffer. @@ -1437,10 +2766,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( * acquired on. The command buffer should be submitted on the thread it was * acquired on. * - * \param device a GPU context. - * \returns a command buffer. + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. * - * \since This function is available since SDL 3.0.0. + * \param device a GPU context. + * \returns a command buffer, or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence @@ -1448,118 +2785,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer( SDL_GPUDevice *device); -/* - * UNIFORM DATA - * - * Uniforms are for passing data to shaders. - * The uniform data will be constant across all executions of the shader. - * - * There are 4 available uniform slots per shader stage (vertex, fragment, compute). - * Uniform data pushed to a slot on a stage keeps its value throughout the command buffer - * until you call the relevant Push function on that slot again. - * - * For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, - * push the camera matrix at the start of the command buffer, and that data will be used for every - * subsequent draw call. - * - * It is valid to push uniform data during a render or compute pass. - * - * Uniforms are best for pushing small amounts of data. - * If you are pushing more than a matrix or two per call you should consider using a storage buffer instead. - */ +/* Uniform Data */ /** * Pushes data to a vertex uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the vertex uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the vertex uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a fragment uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the fragment uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the fragment uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); - -/* - * A NOTE ON CYCLING - * - * When using a command buffer, operations do not occur immediately - - * they occur some time after the command buffer is submitted. - * - * When a resource is used in a pending or active command buffer, it is considered to be "bound". - * When a resource is no longer used in any pending or active command buffers, it is considered to be "unbound". - * - * If data resources are bound, it is unspecified when that data will be unbound - * unless you acquire a fence when submitting the command buffer and wait on it. - * However, this doesn't mean you need to track resource usage manually. - * - * All of the functions and structs that involve writing to a resource have a "cycle" bool. - * GPUTransferBuffer, GPUBuffer, and GPUTexture all effectively function as ring buffers on internal resources. - * When cycle is SDL_TRUE, if the resource is bound, the cycle rotates to the next unbound internal resource, - * or if none are available, a new one is created. - * This means you don't have to worry about complex state tracking and synchronization as long as cycling is correctly employed. - * - * For example: you can call MapTransferBuffer, write texture data, UnmapTransferBuffer, and then UploadToTexture. - * The next time you write texture data to the transfer buffer, if you set the cycle param to SDL_TRUE, you don't have - * to worry about overwriting any data that is not yet uploaded. - * - * Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. - * If you set cycle to SDL_TRUE in the ColorAttachmentInfo struct, you can prevent this data dependency. - * - * Cycling will never undefine already bound data. - * When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. - * You must take care not to read undefined data. - * - * Note that when cycling a texture, the entire texture will be cycled, - * even if only part of the texture is used in the call, - * so you must consider the entire texture to contain undefined data after cycling. - * - * You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. - * It is OK to overwrite unreferenced data in a bound resource without cycling, - * but overwriting a section of data that has already been referenced will produce unexpected results. - */ + Uint32 length); /* Graphics State */ @@ -1574,212 +2854,240 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( * is called. You cannot begin another render pass, or begin a compute pass or * copy pass until you have ended the render pass. * - * \param commandBuffer a command buffer. - * \param colorAttachmentInfos an array of texture subresources with - * corresponding clear values and load/store ops. - * \param colorAttachmentCount the number of color attachments in the - * colorAttachmentInfos array. - * \param depthStencilAttachmentInfo a texture subresource with corresponding - * clear value and load/store ops, may be - * NULL. + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. * \returns a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPURenderPass */ extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUColorAttachmentInfo *colorAttachmentInfos, - Uint32 colorAttachmentCount, - SDL_GPUDepthStencilAttachmentInfo *depthStencilAttachmentInfo); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); /** * Binds a graphics pipeline on a render pass to be used in rendering. * * A graphics pipeline must be bound before making any draw calls. * - * \param renderPass a render pass handle. - * \param graphicsPipeline the graphics pipeline to bind. + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( - SDL_GPURenderPass *renderPass, - SDL_GPUGraphicsPipeline *graphicsPipeline); + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Sets the current viewport state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param viewport the viewport to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( - SDL_GPURenderPass *renderPass, - SDL_GPUViewport *viewport); + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); /** * Sets the current scissor state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param scissor the scissor area to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( - SDL_GPURenderPass *renderPass, - SDL_Rect *scissor); + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); /** * Binds vertex buffers on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param firstBinding the starting bind point for the vertex buffers. - * \param pBindings an array of SDL_GPUBufferBinding structs containing vertex - * buffers and offset values. - * \param bindingCount the number of bindings in the pBindings array. + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstBinding, - SDL_GPUBufferBinding *pBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); /** * Binds an index buffer on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param pBinding a pointer to a struct containing an index buffer and - * offset. - * \param indexElementSize whether the index values in the buffer are 16- or - * 32-bit. + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( - SDL_GPURenderPass *renderPass, - SDL_GPUBufferBinding *pBinding, - SDL_GPUIndexElementSize indexElementSize); + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); /** * Binds texture-sampler pairs for use on the vertex shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the vertex sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the vertex shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage texture to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage texture to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the vertex shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage buffer slot to begin binding from. - * \param storageBuffers an array of buffers. - * \param bindingCount the number of buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage buffer slot to begin binding from. + * \param storage_buffers an array of buffers. + * \param num_bindings the number of buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Binds texture-sampler pairs for use on the fragment shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the fragment sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the fragment shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the fragment shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffers. - * \param bindingCount the number of storage buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffers. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /* Drawing */ @@ -1789,100 +3097,101 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param indexCount the number of vertices to draw per instance. - * \param instanceCount the number of instances to draw. - * \param firstIndex the starting index within the index buffer. - * \param vertexOffset value added to vertex index before indexing into the - * vertex buffer. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 indexCount, - Uint32 instanceCount, - Uint32 firstIndex, - Sint32 vertexOffset, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); /** * Draws data using bound graphics state. * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param vertexCount the number of vertices to draw. - * \param instanceCount the number of instances that will be drawn. - * \param firstVertex the index of the first vertex to draw. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 vertexCount, - Uint32 instanceCount, - Uint32 firstVertex, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); /** * Draws data using bound graphics state and with draw parameters set from a * buffer. * - * The buffer layout should match the layout of SDL_GPUIndirectDrawCommand. - * You must not call this function before binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Draws data using bound graphics state with an index buffer enabled and with * draw parameters set from a buffer. * - * The buffer layout should match the layout of - * SDL_GPUIndexedIndirectDrawCommand. You must not call this function before - * binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Ends the given render pass. @@ -1890,12 +3199,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( * All bound graphics state on the render pass command buffer is unset. The * render pass handle is now invalid. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( - SDL_GPURenderPass *renderPass); + SDL_GPURenderPass *render_pass); /* Compute Pass */ @@ -1903,89 +3212,115 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( * Begins a compute pass on a command buffer. * * A compute pass is defined by a set of texture subresources and buffers that - * will be written to by compute pipelines. These textures and buffers must - * have been created with the COMPUTE_STORAGE_WRITE bit. All operations - * related to compute pipelines must take place inside of a compute pass. You - * must not begin another compute pass, or a render pass or copy pass before - * ending the compute pass. + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. * - * A VERY IMPORTANT NOTE Textures and buffers bound as write-only MUST NOT be - * read from during the compute pass. Doing so will result in undefined - * behavior. If your compute work requires reading the output from a previous - * dispatch, you MUST end the current compute pass and begin a new one before - * you can safely access the data. + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! * - * \param commandBuffer a command buffer. - * \param storageTextureBindings an array of writeable storage texture binding - * structs. - * \param storageTextureBindingCount the number of storage textures to bind - * from the array. - * \param storageBufferBindings an array of writeable storage buffer binding - * structs. - * \param storageBufferBindingCount the number of storage buffers to bind from - * the array. + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. * \returns a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPUComputePass */ extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUStorageTextureWriteOnlyBinding *storageTextureBindings, - Uint32 storageTextureBindingCount, - SDL_GPUStorageBufferWriteOnlyBinding *storageBufferBindings, - Uint32 storageBufferBindingCount); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); /** * Binds a compute pipeline on a command buffer for use in compute dispatch. * - * \param computePass a compute pass handle. - * \param computePipeline a compute pipeline to bind. + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( - SDL_GPUComputePass *computePass, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler bindings to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures as readonly for use on the compute pipeline. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers as readonly for use on the compute pipeline. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffer binding structs. - * \param bindingCount the number of storage buffers to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffer binding structs. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Dispatches compute work. @@ -1997,21 +3332,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. - * \param groupCountX number of local workgroups to dispatch in the X - * dimension. - * \param groupCountY number of local workgroups to dispatch in the Y - * dimension. - * \param groupCountZ number of local workgroups to dispatch in the Z - * dimension. + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( - SDL_GPUComputePass *computePass, - Uint32 groupCountX, - Uint32 groupCountY, - Uint32 groupCountZ); + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); /** * Dispatches compute work with parameters set from a buffer. @@ -2025,16 +3360,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * \param buffer a buffer containing dispatch parameters. - * \param offsetInBytes the offset to start reading from the dispatch buffer. + * \param offset the offset to start reading from the dispatch buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( - SDL_GPUComputePass *computePass, + SDL_GPUComputePass *compute_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes); + Uint32 offset); /** * Ends the current compute pass. @@ -2042,12 +3377,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( * All bound compute state on the command buffer is unset. The compute pass * handle is now invalid. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( - SDL_GPUComputePass *computePass); + SDL_GPUComputePass *compute_pass); /* TransferBuffer Data */ @@ -2057,28 +3392,29 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( * You must unmap the transfer buffer before encoding upload commands. * * \param device a GPU context. - * \param transferBuffer a transfer buffer. - * \param cycle if SDL_TRUE, cycles the transfer buffer if it is bound. - * \returns the address of the mapped transfer buffer memory. + * \param transfer_buffer a transfer buffer. + * \param cycle if true, cycles the transfer buffer if it is already bound. + * \returns the address of the mapped transfer buffer memory, or NULL on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer, - SDL_bool cycle); + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); /** * Unmaps a previously mapped transfer buffer. * * \param device a GPU context. - * \param transferBuffer a previously mapped transfer buffer. + * \param transfer_buffer a previously mapped transfer buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /* Copy Pass */ @@ -2089,13 +3425,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( * inside a copy pass. You must not begin another copy pass, or a render pass * or compute pass before ending the copy pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \returns a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /** * Uploads data from a transfer buffer to a texture. @@ -2106,21 +3442,19 @@ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( * You must align the data in the transfer buffer to a multiple of the texel * size of the texture format. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with image layout information. * \param destination the destination texture region. - * \param cycle if SDL_TRUE, cycles the texture if the texture is bound, - * otherwise overwrites the data. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureTransferInfo *source, - SDL_GPUTextureRegion *destination, - SDL_bool cycle); - -/* Uploads data from a TransferBuffer to a Buffer. */ + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); /** * Uploads data from a transfer buffer to a buffer. @@ -2128,19 +3462,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( * The upload occurs on the GPU timeline. You may assume that the upload has * finished in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with offset. * \param destination the destination buffer with offset and size. - * \param cycle if SDL_TRUE, cycles the buffer if it is bound, otherwise + * \param cycle if true, cycles the buffer if it is already bound, otherwise * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUTransferBufferLocation *source, - SDL_GPUBufferRegion *destination, - SDL_bool cycle); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); /** * Performs a texture-to-texture copy. @@ -2148,27 +3482,25 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source a source texture region. * \param destination a destination texture region. * \param w the width of the region to copy. * \param h the height of the region to copy. * \param d the depth of the region to copy. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination + * \param cycle if true, cycles the destination texture if the destination * texture is bound, otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureLocation *source, - SDL_GPUTextureLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, Uint32 w, Uint32 h, Uint32 d, - SDL_bool cycle); - -/* Copies data from a buffer to a buffer. */ + bool cycle); /** * Performs a buffer-to-buffer copy. @@ -2176,21 +3508,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the buffer and offset to copy from. * \param destination the buffer and offset to copy to. * \param size the length of the buffer to copy. - * \param cycle if SDL_TRUE, cycles the destination buffer if it is bound, + * \param cycle if true, cycles the destination buffer if it is already bound, * otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferLocation *source, - SDL_GPUBufferLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, Uint32 size, - SDL_bool cycle); + bool cycle); /** * Copies data from a texture to a transfer buffer on the GPU timeline. @@ -2198,17 +3530,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source texture region. * \param destination the destination transfer buffer with image layout * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureRegion *source, - SDL_GPUTextureTransferInfo *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); /** * Copies data from a buffer to a transfer buffer on the GPU timeline. @@ -2216,39 +3548,39 @@ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source buffer with offset and size. * \param destination the destination transfer buffer with offset. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferRegion *source, - SDL_GPUTransferBufferLocation *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); /** * Ends the current copy pass. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( - SDL_GPUCopyPass *copyPass); + SDL_GPUCopyPass *copy_pass); /** * Generates mipmaps for the given texture. * * This function must not be called inside of any pass. * - * \param commandBuffer a commandBuffer. + * \param command_buffer a command_buffer. * \param texture a texture with more than 1 mip level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, SDL_GPUTexture *texture); /** @@ -2256,23 +3588,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( * * This function must not be called inside of any pass. * - * \param commandBuffer a command buffer. - * \param source the texture region to copy from. - * \param destination the texture region to copy to. - * \param flipMode the flip mode for the source texture region. - * \param filterMode the filter mode that will be used when blitting. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination - * texture is bound, otherwise overwrites the data. + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUBlitRegion *source, - SDL_GPUBlitRegion *destination, - SDL_FlipMode flipMode, - SDL_GPUFilter filterMode, - SDL_bool cycle); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); /* Submission/Presentation */ @@ -2283,17 +3606,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( * * \param device a GPU context. * \param window an SDL_Window. - * \param swapchainComposition the swapchain composition to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition); + SDL_GPUSwapchainComposition swapchain_composition); /** * Determines whether a presentation mode is supported by the window. @@ -2302,40 +3625,46 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( * * \param device a GPU context. * \param window an SDL_Window. - * \param presentMode the presentation mode to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUPresentMode presentMode); + SDL_GPUPresentMode present_mode); /** * Claims a window, creating a swapchain structure for it. * * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created * the window. * * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain - * parameters, you must call SetSwapchainParameters after claiming the window. + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. * * \param device a GPU context. * \param window an SDL_Window. - * \returns SDL_TRUE on success, otherwise SDL_FALSE. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. * - * \sa SDL_AcquireGPUSwapchainTexture + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_ReleaseWindowFromGPUDevice * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( SDL_GPUDevice *device, SDL_Window *window); @@ -2345,7 +3674,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( * \param device a GPU context. * \param window an SDL_Window that has been claimed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ @@ -2366,29 +3695,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( * * \param device a GPU context. * \param window an SDL_Window that has been claimed. - * \param swapchainComposition the desired composition of the swapchain. - * \param presentMode the desired present mode for the swapchain. - * \returns SDL_TRUE if successful, SDL_FALSE on error. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGPUSwapchainParameters( +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition, - SDL_GPUPresentMode presentMode); + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture pointer with NULL, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight( + SDL_GPUDevice *device, + Uint32 allowed_frames_in_flight); /** * Obtains the texture format of the swapchain for the given window. * + * Note that this format can change if the swapchain parameters change. + * * \param device a GPU context. * \param window an SDL_Window that has been claimed. * \returns the texture format of the swapchain. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( SDL_GPUDevice *device, @@ -2400,28 +3761,118 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma * When a swapchain texture is acquired on a command buffer, it will * automatically be submitted for presentation when the command buffer is * submitted. The swapchain texture should only be referenced by the command - * buffer used to acquire it. May return NULL under certain conditions. This - * is not necessarily an error. This texture is managed by the implementation - * and must not be freed by the user. You MUST NOT call this function from any - * thread other than the one that created the window. + * buffer used to acquire it. * - * \param commandBuffer a command buffer. + * This function will fill the swapchain texture handle with NULL if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. * \param window a window that has been claimed. - * \param pWidth a pointer filled in with the swapchain width. - * \param pHeight a pointer filled in with the swapchain height. - * \returns a swapchain texture. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight */ -extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( - SDL_GPUCommandBuffer *commandBuffer, +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, SDL_Window *window, - Uint32 *pWidth, - Uint32 *pHeight); + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with NULL in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the pointer is NULL before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); /** * Submits a command buffer so its commands can be processed on the GPU. @@ -2433,16 +3884,19 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( - SDL_GPUCommandBuffer *commandBuffer); +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Submits a command buffer so its commands can be processed on the GPU, and @@ -2456,63 +3910,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. - * \returns a fence associated with the command buffer. + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_ReleaseGPUFence */ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); + +/** + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Blocks the thread until the GPU is completely idle. * * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitForGPUFences */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUIdle( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( SDL_GPUDevice *device); /** * Blocks the thread until the given fences are signaled. * * \param device a GPU context. - * \param waitAll if 0, wait for any fence to be signaled, if 1, wait for all - * fences to be signaled. - * \param pFences an array of fences to wait on. - * \param fenceCount the number of fences in the pFences array. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence * \sa SDL_WaitForGPUIdle */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUFences( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( SDL_GPUDevice *device, - SDL_bool waitAll, - SDL_GPUFence **pFences, - Uint32 fenceCount); + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); /** * Checks the status of a fence. * * \param device a GPU context. * \param fence a fence. - * \returns SDL_TRUE if the fence is signaled, SDL_FALSE if it is not. + * \returns true if the fence is signaled, false if it is not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( SDL_GPUDevice *device, SDL_GPUFence *fence); @@ -2522,7 +4007,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( * \param device a GPU context. * \param fence a fence. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ @@ -2535,15 +4020,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( /** * Obtains the texel block size for a texture format. * - * \param textureFormat the texture format you want to know the texel size of. + * \param format the texture format you want to know the texel size of. * \returns the texel block size of the texture format. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( - SDL_GPUTextureFormat textureFormat); + SDL_GPUTextureFormat format); /** * Determines whether a texture format is supported for a given type and @@ -2555,9 +4040,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( * \param usage a bitmask of all usage scenarios to check. * \returns whether the texture format is supported for this type and usage. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( SDL_GPUDevice *device, SDL_GPUTextureFormat format, SDL_GPUTextureType type, @@ -2568,15 +4053,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( * * \param device a GPU context. * \param format the texture format to check. - * \param sampleCount the sample count to check. + * \param sample_count the sample count to check. * \returns a hardware-specific version of min(preferred, possible). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( SDL_GPUDevice *device, SDL_GPUTextureFormat format, - SDL_GPUSampleCount sampleCount); + SDL_GPUSampleCount sample_count); + +/** + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize( + SDL_GPUTextureFormat format, + Uint32 width, + Uint32 height, + Uint32 depth_or_layer_count); #ifdef SDL_PLATFORM_GDK @@ -2589,7 +4091,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -2604,7 +4106,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_guid.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_guid.h index 285b237..e2f32ff 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_guid.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_guid.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,13 +26,14 @@ * * A GUID is a 128-bit value that represents something that is uniquely * identifiable by this value: "globally unique." + * + * SDL provides functions to convert a GUID to/from a string. */ #ifndef SDL_guid_h_ #define SDL_guid_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -55,7 +56,7 @@ extern "C" { * GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs on different operating systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GUID { Uint8 data[16]; @@ -70,7 +71,7 @@ typedef struct SDL_GUID { * \param pszGUID buffer in which to write the ASCII string. * \param cbGUID the size of pszGUID, should be at least 33 bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StringToGUID */ @@ -86,7 +87,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_GUID structure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_haptic.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_haptic.h index 95446fe..a45335b 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_haptic.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_haptic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -66,7 +66,7 @@ * Complete example: * * ```c - * SDL_bool test_haptic(SDL_Joystick *joystick) + * bool test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -74,12 +74,12 @@ * * // Open the device * haptic = SDL_OpenHapticFromJoystick(joystick); - * if (haptic == NULL) return SDL_FALSE; // Most likely joystick isn't haptic + * if (haptic == NULL) return false; // Most likely joystick isn't haptic * * // See if it can do sine waves * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) { * SDL_CloseHaptic(haptic); // No sine effect - * return SDL_FALSE; + * return false; * } * * // Create the effect @@ -106,7 +106,7 @@ * // Close the device * SDL_CloseHaptic(haptic); * - * return SDL_TRUE; // Success + * return true; // Success * } * ``` * @@ -139,15 +139,14 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_OpenHaptic - * \sa SDL_OpenHapticFromJoystick - * \sa SDL_CloseHaptic + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct SDL_Haptic; typedef struct SDL_Haptic SDL_Haptic; @@ -168,7 +167,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Constant haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -179,7 +178,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates sine waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -190,7 +189,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates square waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -201,7 +200,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates triangular waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -212,7 +211,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth up waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -223,7 +222,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth down waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -234,7 +233,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Ramp haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticRamp */ @@ -246,7 +245,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates a spring. Effect is based on the * axes position. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -258,7 +257,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -270,7 +269,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -282,7 +281,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates friction. Effect is based on the * axes movement. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -293,19 +292,31 @@ typedef struct SDL_Haptic SDL_Haptic; * * Haptic effect for direct control over high/low frequency motors. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** @@ -313,7 +324,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * User defined custom haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_CUSTOM (1u<<15) @@ -326,7 +337,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting the global gain. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticGain */ @@ -337,7 +348,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting autocenter. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticAutocenter */ @@ -348,7 +359,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports querying effect status. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus */ @@ -359,7 +370,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Devices supports being paused. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_PauseHaptic * \sa SDL_ResumeHaptic @@ -375,7 +386,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses polar coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -384,7 +395,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses cartesian coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -393,7 +404,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses spherical coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -405,7 +416,7 @@ typedef struct SDL_Haptic SDL_Haptic; * This provides better compatibility across platforms and devices as SDL will * guess the correct axis. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -422,7 +433,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Used to play a device an infinite number of times. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect */ @@ -523,7 +534,7 @@ typedef struct SDL_Haptic SDL_Haptic; * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN @@ -547,7 +558,7 @@ typedef struct SDL_HapticDirection * A constant effect applies a constant force in the specified direction to * the joystick. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect @@ -629,7 +640,7 @@ typedef struct SDL_HapticConstant * \| \| \| \| \| \| \| * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE @@ -685,7 +696,7 @@ typedef struct SDL_HapticPeriodic * SDL_HapticDirection diagram for which side is positive and which is * negative. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticDirection * \sa SDL_HAPTIC_SPRING @@ -699,7 +710,7 @@ typedef struct SDL_HapticCondition /* Header */ Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -728,7 +739,7 @@ typedef struct SDL_HapticCondition * effects get added to the ramp effect making the effect become quadratic * instead of linear. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect @@ -767,7 +778,7 @@ typedef struct SDL_HapticRamp * motors, commonly found in modern game controllers. The small (right) motor * is high frequency, and the large (left) motor is low frequency. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HapticEffect @@ -797,7 +808,7 @@ typedef struct SDL_HapticLeftRight * If channels is one, the effect is rotated using the defined direction. * Otherwise it uses the samples in data for the different axes. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CUSTOM * \sa SDL_HapticEffect @@ -892,7 +903,7 @@ typedef struct SDL_HapticCustom * Note either the attack_level or the fade_level may be above the actual * effect level. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic @@ -921,7 +932,7 @@ typedef union SDL_HapticEffect * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_HapticID; @@ -937,7 +948,7 @@ typedef Uint32 SDL_HapticID; * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -953,7 +964,7 @@ extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticName * \sa SDL_OpenHaptic @@ -974,7 +985,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID ins * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_GetHaptics @@ -993,7 +1004,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id); @@ -1004,7 +1015,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instan * \returns the instance ID of the specified haptic device on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); @@ -1016,7 +1027,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticNameForID */ @@ -1025,13 +1036,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromMouse */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -1039,7 +1050,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); * \returns the haptic device identifier or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsMouseHaptic @@ -1050,13 +1061,13 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. + * \returns true if the joystick is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -1073,7 +1084,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick * \returns a valid haptic device identifier on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsJoystickHaptic @@ -1085,7 +1096,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick * * \param haptic the SDL_Haptic device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -1102,7 +1113,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic); * \returns the number of effects the haptic device can store or a negative * error code on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffectsPlaying * \sa SDL_GetHapticFeatures @@ -1118,7 +1129,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); * \returns the number of effects the haptic device can play at the same time * or -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffects * \sa SDL_GetHapticFeatures @@ -1132,7 +1143,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HapticEffectSupported * \sa SDL_GetMaxHapticEffects @@ -1149,7 +1160,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); * \returns the number of axes on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); @@ -1158,14 +1169,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1176,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti * \returns the ID of the effect on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyHapticEffect * \sa SDL_RunHapticEffect @@ -1196,15 +1207,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_RunHapticEffect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1219,31 +1230,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus * \sa SDL_StopHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1254,7 +1265,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, in * \param haptic the SDL_Haptic device to destroy the effect on. * \param effect the ID of the haptic effect to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect */ @@ -1267,14 +1278,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns SDL_TRUE if it is playing, SDL_FALSE if it isn't playing or haptic - * status isn't supported. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1289,14 +1300,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *hapti * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1308,14 +1319,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int g * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. @@ -1327,14 +1338,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** * Resume a haptic device. @@ -1342,55 +1353,55 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1398,28 +1409,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble * \sa SDL_StopHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hidapi.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hidapi.h index 66bea9d..131b037 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hidapi.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hidapi.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -65,14 +65,14 @@ extern "C" { /** * An opaque handle representing an open HID device. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device SDL_hid_device; /** * HID underlying bus types. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_hid_bus_type { /** Unknown bus type */ @@ -107,7 +107,7 @@ typedef enum SDL_hid_bus_type { /** * Information about a connected HID device * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device_info { @@ -169,7 +169,7 @@ typedef struct SDL_hid_device_info * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_exit */ @@ -184,7 +184,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_init */ @@ -205,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void); * \returns a change counter that is incremented with each potential device * change, or 0 if device change detection isn't available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_enumerate */ @@ -233,7 +233,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); * in the case of failure. Free this linked list by calling * SDL_hid_free_enumeration(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_device_change_count */ @@ -247,7 +247,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho * \param devs pointer to a list of struct_device returned from * SDL_hid_enumerate(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); @@ -265,7 +265,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); @@ -279,7 +279,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_ * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); @@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path) * \returns the actual number of bytes written and -1 on on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne * SDL_GetError() for more information. If no packet was available to * be read within the timeout period, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); @@ -348,7 +348,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign * be read and the handle is in non-blocking mode, this function * returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -367,7 +367,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); @@ -392,7 +392,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int * \returns the actual number of bytes written and -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -415,7 +415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -438,7 +438,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -449,7 +449,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); @@ -462,7 +462,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device * * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -488,7 +488,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -502,7 +502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); @@ -514,7 +514,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, * on failure; call SDL_GetError() for more information. This struct * is valid until the device is closed with SDL_hid_close(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); @@ -530,18 +530,18 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi * \returns the number of bytes actually copied or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. + * \param active true to start the scan, false to stop the scan. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hints.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hints.h index 8433240..8f2d074 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hints.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_hints.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,8 +22,6 @@ /** * # CategoryHints * - * Official documentation for SDL configuration variables - * * This file contains functions to set and get configuration hints, as well as * listing each of them alphabetically. * @@ -63,7 +61,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" @@ -83,7 +81,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" @@ -98,10 +96,27 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" +/** + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" + /** * A variable to control whether we trap the Android back button to handle it * manually. @@ -121,7 +136,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" @@ -137,7 +152,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_ID "SDL_APP_ID" @@ -155,7 +170,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_NAME "SDL_APP_NAME" @@ -178,7 +193,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" @@ -193,7 +208,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" @@ -201,16 +216,58 @@ extern "C" { * Specify the default ALSA audio device name. * * This variable is a specific audio device to open when the "default" audio - * device is used. By default if 4 channel audio is requested, the - * "plug:surround40" device will be opened and if 6 channel audio is requested - * the "plug:surround51" device will be opened. + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE */ #define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" +/** + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" + +/** + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" + /** * A variable controlling the audio category on iOS and macOS. * @@ -225,7 +282,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" @@ -238,7 +295,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" @@ -261,7 +318,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" @@ -283,7 +340,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" @@ -310,7 +367,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" @@ -336,7 +393,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" @@ -347,7 +404,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" @@ -358,7 +415,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" @@ -371,7 +428,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" @@ -385,7 +442,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" @@ -398,7 +455,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" @@ -409,18 +466,23 @@ extern "C" { * device, this hint can be used to specify a default format that will be * used. * - * The variable can be set to the following values: - "U8": Unsigned 8-bit - * audio - "S8": Signed 8-bit audio - "S16LE": Signed 16-bit little-endian - * audio - "S16BE": Signed 16-bit big-endian audio - "S16": Signed 16-bit - * native-endian audio (default) - "S32LE": Signed 32-bit little-endian audio - * - "S32BE": Signed 32-bit big-endian audio - "S32": Signed 32-bit - * native-endian audio - "F32LE": Floating point little-endian audio - - * "F32BE": Floating point big-endian audio - "F32": Floating point - * native-endian audio + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" @@ -433,7 +495,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" @@ -456,7 +518,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" @@ -471,7 +533,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" @@ -486,7 +548,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" @@ -509,7 +571,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" @@ -525,7 +587,7 @@ extern "C" { * best camera backend on your behalf. This hint needs to be set before * SDL_Init() is called to be useful. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" @@ -558,7 +620,7 @@ extern "C" { * * The items can be prefixed by '+'/'-' to add/remove features. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" @@ -572,7 +634,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" @@ -601,7 +663,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" @@ -619,7 +681,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" @@ -640,7 +702,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" @@ -653,7 +715,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" @@ -668,12 +730,13 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all * - any other string without a leading # sign applies to the element on the * page with that ID. * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" @@ -690,7 +753,7 @@ extern "C" { * * This hint must be set before SDL_StartTextInput() is called * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" @@ -707,7 +770,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" @@ -731,7 +794,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" @@ -751,7 +814,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" @@ -772,7 +835,7 @@ extern "C" { * * This hint should be set before calling SDL_GetWindowSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" @@ -787,7 +850,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" @@ -803,7 +866,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" @@ -827,7 +890,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" @@ -845,7 +908,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" @@ -863,7 +926,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" @@ -886,7 +949,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" @@ -898,7 +961,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" @@ -910,7 +973,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" @@ -925,7 +988,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" @@ -941,7 +1004,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" @@ -952,7 +1015,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" @@ -970,7 +1033,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" @@ -988,7 +1051,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" @@ -1002,7 +1065,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" @@ -1011,12 +1074,12 @@ extern "C" { * * By default, SDL will try all available GPU backends in a reasonable order * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "d3d11" if, say, your hardware supports - * D3D12 but want to try using D3D11 instead. + * force a specific target, such as "direct3d11" if, say, your hardware + * supports D3D12 but want to try using D3D11 instead. * - * This hint should be set before SDL_GPUSelectBackend() is called. + * This hint should be set before any GPU functions are called. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" @@ -1035,7 +1098,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" @@ -1052,7 +1115,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" @@ -1075,7 +1138,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" @@ -1094,7 +1157,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" @@ -1111,7 +1174,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" @@ -1128,7 +1191,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" @@ -1149,7 +1212,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" @@ -1167,7 +1230,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" @@ -1188,7 +1251,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" @@ -1198,10 +1261,35 @@ extern "C" { * * This variable is currently only used by the Linux joystick driver. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" +/** + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" + /** * A variable containing a list of flightstick style controllers. * @@ -1215,7 +1303,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" @@ -1236,7 +1324,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" @@ -1246,12 +1334,14 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": GameInput is not used. (default) + * - "0": GameInput is not used. * - "1": GameInput is used. * + * The default is "1" on GDK platforms, and "0" otherwise. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" @@ -1269,7 +1359,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" @@ -1290,7 +1380,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" @@ -1305,9 +1395,9 @@ extern "C" { * This variable is the default for all drivers, but can be overridden by the * hints for specific drivers below. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" @@ -1322,9 +1412,9 @@ extern "C" { * - "1": Left and right Joy-Con controllers will be combined into a single * controller. (default) * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" @@ -1339,9 +1429,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" @@ -1362,7 +1452,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" @@ -1377,9 +1467,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" @@ -1398,7 +1488,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" @@ -1413,9 +1503,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" @@ -1430,9 +1520,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" @@ -1452,9 +1542,9 @@ extern "C" { * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" @@ -1469,9 +1559,9 @@ extern "C" { * * The default value is 0. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" @@ -1486,9 +1576,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" @@ -1503,36 +1593,10 @@ extern "C" { * This hint can be set anytime, but only takes effect when extended input * reports are enabled. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" -/** - * A variable controlling whether extended input reports should be used for - * PS4 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports are enabled. - * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value will also control - * the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for PS5 controllers should * be used. @@ -1544,9 +1608,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" @@ -1559,35 +1623,10 @@ extern "C" { * - "0": player LEDs are not enabled. * - "1": player LEDs are enabled. (default) * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" -/** - * A variable controlling whether extended input reports should be used for - * PS5 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports. - * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value defaults to the - * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD * controllers should be used. @@ -1599,9 +1638,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" @@ -1616,7 +1655,7 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" @@ -1631,12 +1670,31 @@ extern "C" { * Bluetooth access and may prompt the user for permission on iOS and * Android. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" +/** + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" + /** * A variable controlling whether the HIDAPI driver for the Steam Deck builtin * controller should be used. @@ -1648,12 +1706,23 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + /** * A variable controlling whether the HIDAPI driver for Nintendo Switch * controllers should be used. @@ -1665,9 +1734,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" @@ -1686,7 +1755,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" @@ -1701,7 +1770,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" @@ -1717,7 +1786,7 @@ extern "C" { * * This hint should be set before opening a Joy-Con controller. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" @@ -1730,12 +1799,12 @@ extern "C" { * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. + * This driver doesn't work with the dolphinbar, so the default is false for + * now. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" @@ -1750,7 +1819,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" @@ -1766,9 +1835,9 @@ extern "C" { * The default is "0" on Windows, otherwise the value of * SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" @@ -1783,9 +1852,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" @@ -1800,7 +1869,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" @@ -1815,9 +1884,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" @@ -1832,9 +1901,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" @@ -1853,7 +1922,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" @@ -1868,7 +1937,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" @@ -1883,7 +1952,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" @@ -1898,7 +1967,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" @@ -1916,7 +1985,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" @@ -1932,7 +2001,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" @@ -1947,7 +2016,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" @@ -1962,7 +2031,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" @@ -1979,7 +2048,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" @@ -1994,7 +2063,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" @@ -2004,12 +2073,12 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": A separate thread is not used. (default) - * - "1": A separate thread is used for handling raw input messages. + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" @@ -2026,7 +2095,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" @@ -2047,7 +2116,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" @@ -2062,7 +2131,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" @@ -2079,7 +2148,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" @@ -2100,7 +2169,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" @@ -2118,7 +2187,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" @@ -2139,7 +2208,7 @@ extern "C" { * - "latin_letters": For keyboards using non-Latin letters, such as Russian * or Thai, the letter keys generate keycodes as though it had an en_US * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian - * keyboard would yield 'a' instead of 'ф'. + * keyboard would yield 'a' instead of a Cyrillic letter. * * The default value for this hint is "french_numbers,latin_letters" * @@ -2152,7 +2221,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" @@ -2166,7 +2235,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" @@ -2194,7 +2263,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" @@ -2220,7 +2289,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_LOGGING "SDL_LOGGING" @@ -2234,9 +2303,9 @@ extern "C" { * (default) * - "1": The application may remain in the background when launched. * - * This hint should be set before applicationDidFinishLaunching() is called. + * This hint needs to be set before SDL_Init(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" @@ -2252,7 +2321,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" @@ -2275,25 +2344,73 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" +/** + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + +/** + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" + /** * Request SDL_AppIterate() be called at a specific rate. * - * This number is in Hz, so "60" means try to iterate 60 times per second. + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. * * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, * this hint is ignored. When the hint can be used, it is allowed to be * changed at any time. * - * This defaults to 60, and specifying NULL for the hint's value will restore + * This defaults to 0, and specifying NULL for the hint's value will restore * the default. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" @@ -2312,7 +2429,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" @@ -2321,7 +2438,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" @@ -2330,10 +2447,22 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" +/** + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" + /** * A variable controlling whether warping a hidden mouse cursor will activate * relative mouse mode. @@ -2362,7 +2491,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" @@ -2376,7 +2505,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" @@ -2386,7 +2515,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" @@ -2407,32 +2536,17 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" -/** - * A variable controlling whether relative mouse mode is implemented using - * mouse warping. - * - * The variable can be set to the following values: - * - * - "0": Relative mouse mode uses raw input. (default) - * - "1": Relative mouse mode uses mouse warping. - * - * This hint can be set anytime relative mode is not currently enabled. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" - /** * A variable setting the scale for mouse motion, in floating point, when the * mouse is in relative mode. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" @@ -2446,12 +2560,12 @@ extern "C" { * - "1": Relative mouse motion will be scaled using the system mouse * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after * system speed scale. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" @@ -2470,7 +2584,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" @@ -2478,9 +2592,10 @@ extern "C" { * A variable controlling whether the hardware cursor stays visible when * relative mode is active. * - * This variable can be set to the following values: "0" - The cursor will be - * hidden while relative mode is active (default) "1" - The cursor will remain - * visible while relative mode is active + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active * * Note that for systems without raw hardware inputs, relative mode is * implemented using warping, so the hardware cursor will visibly warp between @@ -2488,27 +2603,10 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" -/** - * Controls how often SDL issues cursor confinement commands to the operating - * system while relative mode is active, in case the desired confinement state - * became out-of-sync due to interference from other running programs. - * - * The variable can be integers representing miliseconds between each refresh. - * A value of zero means SDL will not automatically refresh the confinement. - * The default value varies depending on the operating system, this variable - * might not have any effects on inapplicable platforms such as those without - * a cursor. - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" - /** * A variable controlling whether mouse events should generate synthetic touch * events. @@ -2522,7 +2620,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" @@ -2540,7 +2638,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" @@ -2555,7 +2653,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" @@ -2563,12 +2661,25 @@ extern "C" { * Specify the OpenGL library to load. * * This hint should be set before creating an OpenGL window or creating an - * OpenGL context. + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" +/** + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" + /** * A variable controlling what driver to use for OpenGL ES contexts. * @@ -2599,10 +2710,22 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" + /** * A variable controlling which orientations are allowed on iOS/Android. * @@ -2618,7 +2741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" @@ -2638,7 +2761,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" @@ -2656,7 +2779,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" @@ -2673,9 +2796,13 @@ extern "C" { * - "1": SDL will send a quit event when the last window is requesting to * close. (default) * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" @@ -2690,7 +2817,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" @@ -2706,7 +2833,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" @@ -2720,7 +2847,7 @@ extern "C" { * * By default, SDL does not use Vulkan Validation Layers. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" @@ -2734,7 +2861,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" @@ -2749,7 +2876,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" @@ -2758,7 +2885,7 @@ extern "C" { * * If the application doesn't pick a specific renderer to use, this variable * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * can't be initialized, creating a renderer will fail. * * This variable is case insensitive and can be set to the following values: * @@ -2770,14 +2897,19 @@ extern "C" { * - "opengles" * - "metal" * - "vulkan" + * - "gpu" * - "software" * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * * The default varies by platform, but it's the first one in the list that is * available on the current platform. * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" @@ -2795,7 +2927,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" @@ -2810,7 +2942,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" @@ -2827,7 +2959,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" @@ -2844,7 +2976,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" @@ -2861,7 +2993,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. * * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED */ @@ -2883,7 +3015,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" @@ -2895,7 +3027,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" @@ -2917,7 +3049,7 @@ extern "C" { * * This hint should be set before calling SDL_DisableScreenSaver() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" @@ -2936,7 +3068,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" @@ -2950,7 +3082,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" @@ -2964,7 +3096,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" @@ -2991,32 +3123,32 @@ extern "C" { * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling * policy * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** * A string specifying additional information to use with - * SDL_SetThreadPriority. + * SDL_SetCurrentThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. * * pthread hint values are "current", "other", "fifo" and "rr". Currently no * other platform hint values are defined but may be in the future. * * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the * distro configured execution budget for rtkit. This budget can be queried - * through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" @@ -3036,7 +3168,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" @@ -3051,7 +3183,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" @@ -3072,7 +3204,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -3087,7 +3219,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" @@ -3101,10 +3233,35 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" +/** + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" + /** * Tell the video driver that we only want a double buffer. * @@ -3124,7 +3281,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" @@ -3136,9 +3293,13 @@ extern "C" { * force a specific target, such as "x11" if, say, you are on Wayland but want * to try talking to the X server instead. * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" @@ -3151,7 +3312,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" @@ -3165,7 +3326,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" @@ -3181,7 +3342,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" @@ -3199,10 +3360,31 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + /** * A variable controlling whether fullscreen windows are minimized when they * lose focus. @@ -3215,7 +3397,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" @@ -3232,7 +3414,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" @@ -3258,7 +3440,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" @@ -3276,7 +3458,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" @@ -3296,7 +3478,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" @@ -3318,7 +3500,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" @@ -3338,7 +3520,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" @@ -3357,6 +3539,8 @@ extern "C" { * * - Rounding errors can result with odd window sizes and/or desktop scales, * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. * - The window may be unusably small on scaled desktops. * - The window may jump in size when moving between displays of different * scale factors. @@ -3375,7 +3559,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" @@ -3397,7 +3581,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" @@ -3412,7 +3596,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" @@ -3431,7 +3615,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" @@ -3445,7 +3629,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" @@ -3456,7 +3640,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" @@ -3465,7 +3649,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" @@ -3474,7 +3658,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" @@ -3488,7 +3672,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" @@ -3503,7 +3687,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" @@ -3518,7 +3702,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" @@ -3529,7 +3713,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" @@ -3542,7 +3726,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" @@ -3557,7 +3741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" @@ -3572,7 +3756,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" @@ -3588,7 +3772,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" @@ -3599,7 +3783,7 @@ extern "C" { * * This hint should be set before calling SDL_Vulkan_CreateSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" @@ -3609,7 +3793,7 @@ extern "C" { * This hint should be set before creating a Vulkan window or calling * SDL_Vulkan_LoadLibrary(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" @@ -3641,7 +3825,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" @@ -3653,7 +3837,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" @@ -3681,7 +3865,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" @@ -3701,7 +3885,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" @@ -3718,7 +3902,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" @@ -3735,7 +3919,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" @@ -3753,7 +3937,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" @@ -3769,7 +3953,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" @@ -3785,7 +3969,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" @@ -3814,7 +3998,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" @@ -3829,7 +4013,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" @@ -3845,7 +4029,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" @@ -3859,7 +4043,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" @@ -3880,7 +4064,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" @@ -3890,9 +4074,18 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** @@ -3917,7 +4110,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" @@ -3934,123 +4127,10 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" -/** - * A variable controlling whether back-button-press events on Windows Phone to - * be marked as handled. - * - * Windows Phone devices typically feature a Back button. When pressed, the OS - * will emit back-button-press events, which apps are expected to handle in an - * appropriate manner. If apps do not explicitly mark these events as - * 'Handled', then the OS will invoke its default behavior for unhandled - * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate - * the app (and attempt to switch to the previous app, or to the device's home - * screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to - * mark back-button-press events as Handled, if and when one is sent to the - * app. - * - * Internally, Windows Phone sends back button events as parameters to special - * back-button-press callback functions. Apps that need to respond to - * back-button-press events are expected to register one or more callback - * functions for such, shortly after being launched (during the app's - * initialization phase). After the back button is pressed, the OS will invoke - * these callbacks. If the app's callback(s) do not explicitly mark the event - * as handled by the time they return, or if the app never registers one of - * these callback, the OS will consider the event un-handled, and it will - * apply its default back button behavior (terminate the app). - * - * SDL registers its own back-button-press callback with the Windows Phone OS. - * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN - * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after - * which it will check the contents of the hint, - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the - * back button event's Handled property will get set to 'true'. If the hint's - * value is set to something else, or if it is unset, SDL will leave the - * event's Handled property alone. (By default, the OS sets this property to - * 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for - * either event type is suitable.) Any value of - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied - * to the OS' current back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found at - * the following page, on Microsoft's developer site: - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** - * A variable specifying the label text for a WinRT app's privacy policy link. - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, - * 8.1, and RT, Microsoft mandates that this policy be available via the - * Windows Settings charm. SDL provides code to add a link there, with its - * label text being set via the optional hint, - * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A - * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the - * actual text of the policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". - * - * For additional information on linking to a privacy policy, see the - * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. - * - * This hint should be set before SDL is initialized. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A variable specifying the URL to a WinRT app's privacy policy. - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - /** * A variable controlling whether X11 windows are marked as override-redirect. * @@ -4068,7 +4148,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" @@ -4085,18 +4165,18 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** * Specify the XCB library to load for the X11 driver. * - * This defaults to "libX11-xcb.so" + * The default is platform-specific, often "libX11-xcb.so.1". * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" @@ -4111,7 +4191,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" @@ -4135,15 +4215,45 @@ extern "C" { * This hint should be set before an assertion failure is triggered and can be * changed at any time. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ASSERT "SDL_ASSERT" +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + /** * An enumeration of hint priorities. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_HintPriority { @@ -4162,18 +4272,18 @@ typedef enum SDL_HintPriority * \param name the hint to set. * \param value the value of the hint variable. * \param priority the SDL_HintPriority level for the hint. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); /** * Set a hint with normal priority. @@ -4184,18 +4294,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, c * * \param name the hint to set. * \param value the value of the hint variable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); /** * Reset a hint to the default value. @@ -4205,17 +4315,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *v * change. * * \param name the hint to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_ResetHints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); /** * Reset all hints to the default values. @@ -4226,7 +4336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetHint */ @@ -4245,7 +4355,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); * callback instead is always thread-safe, as SDL holds a lock * on the thread subsystem during the callback. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_SetHintWithPriority @@ -4262,12 +4372,12 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); /** * A callback used to send notifications of hint value changes. @@ -4284,7 +4394,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo * hint value. SDL holds a lock on the hint subsystem when * calling this callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ @@ -4300,16 +4410,16 @@ typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * \param callback An SDL_HintCallback function that will be called when the * hint value changes. * \param userdata a pointer to pass to the callback function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveHintCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); /** * Remove a function watching a particular hint. @@ -4321,7 +4431,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_H * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_init.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_init.h index 5a13947..adf0de8 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_init.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_init.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,10 +22,30 @@ /** * # CategoryInit * - * SDL subsystem init and quit functions. + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). */ - #ifndef SDL_init_h_ #define SDL_init_h_ @@ -47,7 +67,7 @@ extern "C" { * These are the flags which may be passed to SDL_Init(). You should specify * the subsystems which you will be using in your application. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -57,9 +77,8 @@ extern "C" { */ typedef Uint32 SDL_InitFlags; -#define SDL_INIT_TIMER 0x00000001u #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ -#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */ #define SDL_INIT_HAPTIC 0x00001000u #define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ @@ -85,7 +104,7 @@ typedef Uint32 SDL_InitFlags; * [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. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AppResult { @@ -94,10 +113,70 @@ typedef enum SDL_AppResult SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ } SDL_AppResult; +/** + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); + +/** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ 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); + +/** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); + +/** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. @@ -117,11 +196,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * * `flags` may be any of the following OR'd together: * - * - `SDL_INIT_TIMER`: timer subsystem * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem + * subsystem, should be initialized on the main thread. * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem @@ -143,10 +221,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * SDL_SetAppMetadataProperty(). * * \param flags subsystem initialization flags. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty @@ -155,7 +233,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * \sa SDL_SetMainReady * \sa SDL_WasInit */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Init(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); /** * Compatibility function to initialize the SDL library. @@ -163,16 +241,16 @@ extern SDL_DECLSPEC SDL_bool 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit * \sa SDL_QuitSubSystem */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); /** * Shut down specific SDL subsystems. @@ -182,7 +260,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem * \sa SDL_Quit @@ -196,7 +274,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_InitSubSystem @@ -214,13 +292,70 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); * application is shutdown, but it is not wise to do this from a library or * other dynamically loaded code. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_QuitSubSystem */ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); +/** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void); + +/** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata); + +/** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete); + /** * Specify basic metadata about your app. * @@ -248,16 +383,16 @@ 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadataProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); /** * Specify metadata about your app through a set of properties. @@ -274,7 +409,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * Multiple calls to this function are allowed, but various state might not * change once it has been set up with a previous call to this function. * - * Once set, this metadata can be read using SDL_GetMetadataProperty(). + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). * * These are the supported properties: * @@ -310,17 +445,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * * \param name the name of the metadata property to set. * \param value the value of the property, or NULL to remove that property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); +extern SDL_DECLSPEC 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" @@ -346,7 +481,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name * freed if you call SDL_SetAppMetadataProperty() to set that * property from another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_intrin.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_intrin.h index efba11d..bac6d7a 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_intrin.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_intrin.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -19,8 +19,31 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * Header file for CPU intrinsics for SDL +/* WIKI CATEGORY: Intrinsics */ + +/** + * # CategoryIntrinsics + * + * SDL does some preprocessor gymnastics to determine if any CPU-specific + * compiler intrinsics are available, as this is not necessarily an easy thing + * to calculate, and sometimes depends on quirks of a system, versions of + * build tools, and other external forces. + * + * Apps including SDL's headers will be able to check consistent preprocessor + * definitions to decide if it's safe to use compiler intrinsics for a + * specific CPU architecture. This check only tells you that the compiler is + * capable of using those intrinsics; at runtime, you should still check if + * they are available on the current system with the + * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo) + * , such as SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash + * for using an unsupported CPU instruction. + * + * SDL only sets preprocessor defines for CPU intrinsics if they are + * supported, so apps should check with `#ifdef` and not `#if`. + * + * SDL will also include the appropriate instruction-set-specific support + * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will also + * `#include ` as well. */ #ifndef SDL_intrin_h_ @@ -28,6 +51,169 @@ #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LSX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LASX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports ARM NEON intrinsics. + * + * If this macro is defined, SDL will have already included `` + * ``, ``, and ``, as appropriate. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NEON_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports PowerPC Altivec intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALTIVEC_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel MMX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + */ +#define SDL_MMX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE3 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE3_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE4_1_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + */ +#define SDL_SSE4_2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX2_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics. + * + * AVX-512F is also sometimes referred to as "AVX-512 Foundation." + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX2_INTRINSICS + */ +#define SDL_AVX512F_INTRINSICS 1 +#endif + /* Need to do this here because intrin.h has C++ code in it */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) @@ -81,7 +267,21 @@ _m_prefetch(void *__P) #endif #endif /* compiler version */ -#if defined(__clang__) && defined(__has_attribute) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro to decide if the compiler supports `__attribute__((target))`. + * + * Even though this is defined in SDL's public headers, it is generally not + * used directly by apps. Apps should probably just use SDL_TARGETING + * directly, instead. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) # if __has_attribute(target) # define SDL_HAS_TARGET_ATTRIBS # endif @@ -91,7 +291,55 @@ _m_prefetch(void *__P) # define SDL_HAS_TARGET_ATTRIBS #endif -#ifdef SDL_HAS_TARGET_ATTRIBS + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a function as targeting a specific CPU architecture. + * + * This is a hint to the compiler that a function should be built with support + * for a CPU instruction set that might be different than the rest of the + * program. + * + * The particulars of this are explained in the GCC documentation: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute + * + * An example of using this feature is to turn on SSE2 support for a specific + * function, even if the rest of the source code is not compiled to use SSE2 + * code: + * + * ```c + * #ifdef SDL_SSE2_INTRINSICS + * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) { + * ...use SSE2 intrinsic functions, etc... + * } + * #endif + * + * // later... + * #ifdef SDL_SSE2_INTRINSICS + * if (SDL_HasSSE2()) { + * DoSomethingWithSSE2(str); + * } + * #endif + * ``` + * + * The application is, on a whole, built without SSE2 instructions, so it will + * run on Intel machines that don't support SSE2. But then at runtime, it + * checks if the system supports the instructions, and then calls into a + * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't + * used on platforms that don't have SSE2 at all. + * + * On compilers without target support, this is defined to nothing. + * + * This symbol is used by SDL internally, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TARGETING(x) __attribute__((target(x))) + +#elif defined(SDL_HAS_TARGET_ATTRIBS) # define SDL_TARGETING(x) __attribute__((target(x))) #else # define SDL_TARGETING(x) diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_iostream.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_iostream.h index a306deb..4ca1609 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_iostream.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_iostream.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,7 @@ * # CategoryIOStream * * SDL provides an abstract interface for reading and writing data streams. It - * offers implementations for files, memory, etc, and the app can provideo + * offers implementations for files, memory, etc, and the app can provide * their own implementations, too. * * SDL_IOStream is not related to the standard C++ iostream class, other than @@ -48,7 +48,7 @@ extern "C" { /** * SDL_IOStream status, set by a read or write operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOStatus { @@ -66,13 +66,13 @@ typedef enum SDL_IOStatus * These map to the same "whence" concept that `fseek` or `lseek` use in the * standard C runtime. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOWhence { SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ - SDL_IO_SEEK_END, /**< Seek relative to the end of data */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ } SDL_IOWhence; /** @@ -83,10 +83,17 @@ typedef enum SDL_IOWhence * already offers several common types of I/O streams, via functions like * SDL_IOFromFile() and SDL_IOFromMem(). * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_IOStreamInterface { + /* The version of this interface */ + Uint32 version; + /** * Return the number of bytes in this SDL_IOStream * @@ -126,18 +133,41 @@ typedef struct SDL_IOStreamInterface */ size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + /** * Close and free any allocated resources. * - * The SDL_IOStream is still destroyed even if this fails, so clean up anything - * even if flushing to disk returns an error. + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. * - * \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data. + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); } SDL_IOStreamInterface; +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); /** * The read/write operation structure. @@ -147,7 +177,7 @@ typedef struct SDL_IOStreamInterface * SDL_OpenIO() to provide their own stream implementation behind this * struct's abstract interface. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_IOStream SDL_IOStream; @@ -217,6 +247,8 @@ typedef struct SDL_IOStream SDL_IOStream; * than your app, trying to use this pointer will almost certainly result in * a crash! This is mostly a problem on Windows; make sure you build SDL and * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access * the filesystem. If SDL used some other method to access the filesystem, @@ -228,9 +260,12 @@ typedef struct SDL_IOStream SDL_IOStream; * \returns a pointer to the SDL_IOStream structure that is created or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -240,6 +275,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" /** @@ -257,15 +293,25 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromConstMem * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -273,6 +319,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons */ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + /** * Use this function to prepare a read-only memory buffer for use with * SDL_IOStream. @@ -290,12 +339,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * If you need to write to a memory buffer, you should use SDL_IOFromMem() * with a writable buffer of memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromMem * \sa SDL_CloseIO @@ -323,7 +381,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO * \sa SDL_ReadIO @@ -347,20 +407,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * read/write a common data source, you should use the built-in * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. * - * You must free the returned pointer with SDL_CloseIO(). - * * This function makes a copy of `iface` and the caller does not need to keep - * this data around after this call. + * it around after this call. * - * \param iface the function pointers that implement this SDL_IOStream. - * \param userdata the app-controlled pointer that is passed to iface's - * functions when called. + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a pointer to the allocated memory on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE * \sa SDL_IOFromConstMem * \sa SDL_IOFromFile * \sa SDL_IOFromMem @@ -372,21 +433,32 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any * resources used by the stream and frees the SDL_IOStream itself. This - * returns SDL_TRUE on success, or SDL_FALSE if the stream failed to flush to - * its output (e.g. to disk). + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). * - * Note that if this fails to flush the stream to disk, this function reports - * an error, but the SDL_IOStream is still invalid once this function returns. + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. * * \param context SDL_IOStream structure to close. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenIO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); /** * Get the properties associated with an SDL_IOStream. @@ -395,7 +467,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); @@ -413,10 +487,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *c * \param context the SDL_IOStream to query. * \returns an SDL_IOStatus enum with the current state. * - * \threadsafety This function should not be called at the same time that - * another thread is operating on the same SDL_IOStream. + * \threadsafety This function is not thread safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); @@ -428,7 +501,9 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); * negative error code on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); @@ -450,10 +525,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * negative. * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, * `SDL_IO_SEEK_END`. - * \returns the final offset in the data stream after the seek or a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TellIO */ @@ -471,7 +548,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs * \returns the current offset in the stream, or -1 if the information can not * be determined. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SeekIO */ @@ -481,10 +560,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * Read from a data source. * * This function reads up `size` bytes from the data source to the area - * pointed at by `ptr`. This function may read less bytes than requested. It - * will return zero when the data stream is completely read, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR. + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. * * \param context a pointer to an SDL_IOStream structure. * \param ptr a pointer to a buffer to read data into. @@ -492,7 +573,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * \returns the number of bytes read, or 0 on end of file or other failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WriteIO * \sa SDL_GetIOStatus @@ -519,11 +602,14 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \returns the number of bytes written, which will be less than `size` on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_ReadIO * \sa SDL_SeekIO + * \sa SDL_FlushIO * \sa SDL_GetIOStatus */ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); @@ -540,7 +626,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOvprintf * \sa SDL_WriteIO @@ -558,13 +646,35 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_WriteIO */ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + /** * Load all the data from an SDL data stream. * @@ -575,17 +685,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * The data should be freed with SDL_free(). * * \param src the SDL_IOStream to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio); +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); /** * Load all the data from a file path. @@ -601,12 +715,55 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile */ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); +/** + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); + +/** + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); + /** * \name Read endian functions * @@ -617,26 +774,63 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi /** * Use this function to read a byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure or EOF; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); /** * Use this function to read a signed byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of little-endian data from an @@ -645,30 +839,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value) * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data. - * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); - -/** - * Use this function to read 16 bits of little-endian data from an - * SDL_IOStream and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -677,14 +862,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -693,14 +885,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -709,14 +908,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -725,14 +931,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -741,14 +954,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -757,14 +977,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -773,14 +1000,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -789,14 +1023,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -805,14 +1046,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -821,14 +1069,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); /* @} *//* Read endian functions */ /** @@ -843,24 +1098,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); /** * Use this function to write a signed byte to an SDL_IOStream. * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -872,12 +1131,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value) * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -889,12 +1150,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -905,12 +1168,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -921,12 +1186,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -938,12 +1205,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -955,12 +1224,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -971,12 +1242,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -987,12 +1260,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1004,12 +1279,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1021,12 +1298,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1037,12 +1316,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1053,12 +1334,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); /* @} *//* Write endian functions */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_joystick.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_joystick.h index 43bc1e9..d15668b 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_joystick.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_joystick.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,8 +25,8 @@ * SDL joystick support. * * This is the lower-level joystick handling. If you want the simpler option, - * where what buttons does what is well-defined, you should use the gamepad - * API instead. + * where what each button does is well-defined, you should use the gamepad API + * instead. * * The term "instance_id" is the current instantiation of a joystick device in * the system, if the joystick is removed and then re-inserted then it will @@ -81,7 +81,7 @@ extern SDL_Mutex *SDL_joystick_lock; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Joystick SDL_Joystick; @@ -93,7 +93,7 @@ typedef struct SDL_Joystick SDL_Joystick; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_JoystickID; @@ -107,7 +107,7 @@ typedef Uint32 SDL_JoystickID; * This is by no means a complete list of everything that can be plugged into * a computer. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickType { @@ -120,7 +120,8 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_GUITAR, SDL_JOYSTICK_TYPE_DRUM_KIT, SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT } SDL_JoystickType; /** @@ -129,7 +130,7 @@ typedef enum SDL_JoystickType * This is used by SDL_GetJoystickConnectionState to report how a device is * connected to the system. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickConnectionState { @@ -142,7 +143,7 @@ typedef enum SDL_JoystickConnectionState /** * The largest value an SDL_Joystick's axis can report. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MIN */ @@ -153,19 +154,13 @@ typedef enum SDL_JoystickConnectionState * * This is a negative number! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MAX */ #define SDL_JOYSTICK_AXIS_MIN -32768 -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - /* Function prototypes */ /** @@ -175,27 +170,27 @@ typedef enum SDL_JoystickConnectionState * joysticks while processing to guarantee that the joystick list won't change * and joystick and gamepad events will not be delivered. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); /** * Unlocking for atomic access to the joystick API. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); /** * Return whether a joystick is currently connected. * - * \returns SDL_TRUE if a joystick is connected, SDL_FALSE otherwise. + * \returns true if a joystick is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. @@ -206,7 +201,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasJoystick * \sa SDL_OpenJoystick @@ -222,7 +217,7 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickName * \sa SDL_GetJoysticks @@ -238,7 +233,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPath * \sa SDL_GetJoysticks @@ -253,7 +248,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a joystick, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoysticks @@ -269,7 +264,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID i * \returns the GUID of the selected joystick. If called with an invalid * instance_id, this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUID * \sa SDL_GUIDToString @@ -286,7 +281,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID ins * \returns the USB vendor ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendor * \sa SDL_GetJoysticks @@ -303,7 +298,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID ins * \returns the USB product ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProduct * \sa SDL_GetJoysticks @@ -320,7 +315,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID in * \returns the product version of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersion * \sa SDL_GetJoysticks @@ -337,7 +332,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_Joysti * invalid instance_id, this function returns * `SDL_JOYSTICK_TYPE_UNKNOWN`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickType * \sa SDL_GetJoysticks @@ -354,7 +349,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti * \returns a joystick identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseJoystick */ @@ -367,7 +362,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID insta * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); @@ -378,7 +373,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_SetJoystickPlayerIndex @@ -388,7 +383,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int pl /** * The structure that describes a virtual joystick touchpad. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -401,7 +396,7 @@ typedef struct SDL_VirtualJoystickTouchpadDesc /** * The structure that describes a virtual joystick sensor. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -414,16 +409,19 @@ typedef struct SDL_VirtualJoystickSensorDesc /** * The structure that describes a virtual joystick. * - * All elements of this structure are optional and can be left 0. + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE * \sa SDL_VirtualJoystickSensorDesc * \sa SDL_VirtualJoystickTouchpadDesc */ typedef struct SDL_VirtualJoystickDesc { + Uint32 version; /**< the version of this interface */ Uint16 type; /**< `SDL_JoystickType` */ Uint16 padding; /**< unused */ Uint16 vendor_id; /**< the USB vendor ID of this joystick */ @@ -446,22 +444,32 @@ typedef struct SDL_VirtualJoystickDesc void *userdata; /**< User data pointer passed to callbacks */ void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - SDL_bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - SDL_bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - SDL_bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - SDL_bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - SDL_bool (SDLCALL *SetSensorsEnabled)(void *userdata, SDL_bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ } SDL_VirtualJoystickDesc; +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + /** * Attach a new virtual joystick. * - * \param desc joystick description. + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DetachVirtualJoystick */ @@ -472,24 +480,24 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V * * \param instance_id the joystick instance ID, previously returned from * SDL_AttachVirtualJoystick(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); /** * Query whether or not a joystick is virtual. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * \returns true if the joystick is virtual, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); /** * Set the state of an axis on an opened virtual joystick. @@ -507,12 +515,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instan * \param joystick the virtual joystick on which to set state. * \param axis the index of the axis on the virtual joystick to update. * \param value the new value for the specified axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); /** * Generate ball motion on an opened virtual joystick. @@ -527,12 +535,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *jo * \param ball the index of the ball on the virtual joystick to update. * \param xrel the relative motion on the X axis. * \param yrel the relative motion on the Y axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); /** * Set the state of a button on an opened virtual joystick. @@ -545,13 +553,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *jo * * \param joystick the virtual joystick on which to set state. * \param button the index of the button on the virtual joystick to update. - * \param value the new value for the specified button. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); /** * Set the state of a hat on an opened virtual joystick. @@ -565,12 +573,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick * * \param joystick the virtual joystick on which to set state. * \param hat the index of the hat on the virtual joystick to update. * \param value the new value for the specified hat. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); /** * Set touchpad finger state on an opened virtual joystick. @@ -585,19 +593,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joy * \param touchpad the index of the touchpad on the virtual joystick to * update. * \param finger the index of the finger on the touchpad to set. - * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the - * finger is released. + * \param down true if the finger is pressed, false if the finger is released. * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param pressure the pressure of the finger. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); /** * Send a sensor update for an opened virtual joystick. @@ -614,12 +621,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick * the sensor reading. * \param data the data associated with the sensor reading. * \param num_values the number of values pointed to by `data`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); /** * Get the properties associated with a joystick. @@ -641,7 +648,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joyst * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); @@ -658,7 +665,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickNameForID */ @@ -671,7 +678,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPathForID */ @@ -686,7 +693,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joyst * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the player index, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickPlayerIndex */ @@ -698,14 +705,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param player_index player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); /** * Get the implementation-dependent GUID for the joystick. @@ -717,7 +724,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *jo * this function returns a zero GUID; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GUIDToString @@ -732,7 +739,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendorForID */ @@ -746,7 +753,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductForID */ @@ -760,7 +767,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the product version of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersionForID */ @@ -775,7 +782,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j * \returns the firmware version of the selected joystick, or 0 if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); @@ -788,7 +795,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick * * \returns the serial number of the selected joystick, or NULL if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); @@ -798,7 +805,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the SDL_JoystickType of the selected joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickTypeForID */ @@ -817,7 +824,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j * \param crc16 a pointer filled in with a CRC used to distinguish different * products with the same VID/PID, or 0 if not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID */ @@ -827,12 +834,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 * * Get the status of a specified joystick. * * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); /** * Get the instance ID of an opened joystick. @@ -841,7 +848,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic * \returns the instance ID of the specified joystick on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); @@ -856,7 +863,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst * \returns the number of axis controls/number of axes on success or -1 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickAxis * \sa SDL_GetNumJoystickBalls @@ -877,7 +884,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); * \returns the number of trackballs on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickBall * \sa SDL_GetNumJoystickAxes @@ -893,7 +900,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); * \returns the number of POV hats on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickHat * \sa SDL_GetNumJoystickAxes @@ -909,7 +916,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); * \returns the number of buttons on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickButton * \sa SDL_GetNumJoystickAxes @@ -927,12 +934,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick * * \param enabled whether to process joystick events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_JoystickEventsEnabled * \sa SDL_UpdateJoysticks */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); /** * Query the state of joystick event processing. @@ -941,14 +948,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); * yourself and check the state of the joystick when you want joystick * information. * - * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE - * otherwise. + * \returns true if joystick events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); /** * Update the current state of the open joysticks. @@ -956,7 +962,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); * This is called automatically by the event loop if any joystick events are * enabled. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); @@ -978,7 +984,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); * \returns a 16-bit signed integer representing the current position of the * axis or 0 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickAxes */ @@ -994,11 +1000,11 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i * \param joystick an SDL_Joystick structure containing joystick information. * \param axis the axis to query; the axis indices start at index 0. * \param state upon return, the initial value is supplied here. - * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \returns true if this axis has any initial value, or false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); /** * Get the ball axis change since the last poll. @@ -1012,14 +1018,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic * \param ball the ball index to query; ball indices start at index 0. * \param dx stores the difference in the x axis position since the last poll. * \param dy stores the difference in the y axis position since the last poll. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickBalls */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); /** * Get the current state of a POV hat on a joystick. @@ -1030,7 +1036,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickHats */ @@ -1052,13 +1058,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickButtons */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); /** * Start a rumble effect. @@ -1075,11 +1081,11 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE, or SDL_FALSE if rumble isn't supported on this joystick. + * \returns true, or false if rumble isn't supported on this joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the joystick's triggers. @@ -1101,14 +1107,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a joystick's LED color. @@ -1123,12 +1129,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *jo * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** * Send a joystick specific effect packet. @@ -1136,19 +1142,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, * \param joystick the joystick to affect. * \param data the data to send to the joystick. * \param size the size of the data to send to the joystick. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); /** * Close a joystick previously opened with SDL_OpenJoystick(). * * \param joystick the joystick device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenJoystick */ @@ -1162,7 +1168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); @@ -1183,7 +1189,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keyboard.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keyboard.h index ec6c3f2..afa77b6 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keyboard.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keyboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeyboard * * SDL keyboard management. + * + * Please refer to the Best Keyboard Practices document for details on how + * best to accept keyboard input in various types of programs: + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keyboard_h_ @@ -31,6 +36,9 @@ #include #include #include +#include +#include +#include #include #include @@ -47,7 +55,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_KeyboardID; @@ -56,13 +64,15 @@ typedef Uint32 SDL_KeyboardID; /** * Return whether a keyboard is currently connected. * - * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise. + * \returns true if a keyboard is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); /** * Get a list of currently connected keyboards. @@ -78,7 +88,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardNameForID * \sa SDL_HasKeyboard @@ -94,7 +106,9 @@ extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); * \returns the name of the selected keyboard or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ @@ -105,7 +119,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID * * \returns the window with keyboard focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); @@ -116,9 +132,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * valid for the whole lifetime of the application and should not be freed by * the caller. * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. + * A array element with a value of true means that the key is pressed and a + * value of false means that it is not. Indexes into this array are obtained + * by using SDL_Scancode values. * * Use SDL_PumpEvents() to update the state array. * @@ -133,19 +149,23 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PumpEvents * \sa SDL_ResetKeyboard */ -extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys); +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); /** * Clear the state of the keyboard. * * This function will generate key up events for all pressed keys. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState */ @@ -157,7 +177,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); * \returns an OR'd combination of the modifier keys for the keyboard. See * SDL_Keymod for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState * \sa SDL_SetModState @@ -177,7 +199,9 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * * \param modstate the desired SDL_Keymod for the keyboard. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetModState */ @@ -189,21 +213,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * If you want to get the keycode as it would be delivered in key events, * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should - * pass `key_event` as SDL_TRUE. Otherwise this function simply translates the + * pass `key_event` as true. Otherwise this function simply translates the * scancode based on the given modifier state. * * \param scancode the desired SDL_Scancode to query. * \param modstate the modifier state to use when translating the scancode to * a keycode. - * \param key_event SDL_TRUE if the keycode will be used in key events. + * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyName * \sa SDL_GetScancodeFromKey */ -extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, SDL_bool key_event); +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); /** * Get the scancode corresponding to the given key code according to the @@ -217,7 +243,9 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan * scancode generates this key, may be NULL. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetScancodeName @@ -231,14 +259,16 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \param name the name to use for the scancode, encoded as UTF-8. The string * is not copied, so the pointer given to this function must stay * valid while SDL is being used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeName */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); /** * Get a human-readable name for a scancode. @@ -256,7 +286,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, * \returns a pointer to the name for the scancode. If the scancode doesn't * have a name this function returns an empty string (""). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeFromKey * \sa SDL_GetScancodeFromName @@ -271,7 +303,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scanco * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't * recognized; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetScancodeFromKey @@ -284,10 +318,14 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * * If the key doesn't have a name, this function returns an empty string (""). * + * Letters will be presented in their uppercase form, if applicable. + * * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetKeyFromScancode @@ -302,7 +340,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetKeyName @@ -319,20 +359,24 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * \param window the window to enable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInputWithProperties * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); /** * Text input type. @@ -341,7 +385,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); * value is valid on every platform, but where a value isn't supported, a * reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -361,12 +405,11 @@ typedef enum SDL_TextInputType /** * Auto capitalization type. * - * These are the valid values for - * SDL_PROP_TEXTINPUT_AUTOCAPITALIZATION_NUMBER. Not every value is valid on - * every platform, but where a value isn't supported, a reasonable fallback - * will be used. + * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. + * Not every value is valid on every platform, but where a value isn't + * supported, a reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -388,7 +431,9 @@ typedef enum SDL_Capitalization * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * These are the supported properties: * @@ -400,11 +445,11 @@ typedef enum SDL_Capitalization * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail * addresses, usernames, and passwords. * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion - * and auto correction, defaults to SDL_TRUE. + * and auto correction, defaults to true. * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text - * are allowed. This defaults to SDL_TRUE if SDL_HINT_RETURN_KEY_HIDES_IME - * is "0" or is not set, and defaults to SDL_FALSE if - * SDL_HINT_RETURN_KEY_HIDES_IME is "1". + * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is + * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME + * is "1". * * On Android you can directly specify the input type: * @@ -414,17 +459,19 @@ typedef enum SDL_Capitalization * * \param window the window to enable text input. * \param props the properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInput * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" @@ -436,13 +483,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window * Check whether or not Unicode text input events are enabled for a window. * * \param window the window to check. - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * \returns true if text input events are enabled else false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); /** * Stop receiving any text input events in a window. @@ -451,28 +500,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); * it. * * \param window the window to disable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); /** * Dismiss the composition window/IME without disabling the subsystem. * * \param window the window to affect. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); /** * Set the area used to type Unicode text input. @@ -485,15 +538,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); * coordinates, or NULL to clear it. * \param cursor the offset of the current cursor location relative to * `rect->x`, in window coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextInputArea * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); /** * Get the area used to type Unicode text input. @@ -505,39 +560,45 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, co * may be NULL. * \param cursor a pointer to the offset of the current cursor location * relative to `rect->x`, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); /** * Check whether the platform has screen keyboard support. * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. + * \returns true if the platform has some screen keyboard support or false if + * not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_ScreenKeyboardShown */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * Check whether the screen keyboard is shown for given window. * * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * \returns true if screen keyboard is shown or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasScreenKeyboardSupport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keycode.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keycode.h index 2d03a3d..61b68e7 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keycode.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_keycode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeycode * * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keycode_h_ @@ -42,272 +47,284 @@ * A special exception is the number keys at the top of the keyboard which map * to SDLK_0...SDLK_9 on AZERTY layouts. * - * \since This datatype is available since SDL 3.0.0. + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_Keycode; -#define SDLK_SCANCODE_MASK (1u<<30) +#define SDLK_EXTENDED_MASK (1u << 29) +#define SDLK_SCANCODE_MASK (1u << 30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -#define SDLK_UNKNOWN 0x00000000u /* 0 */ -#define SDLK_RETURN 0x0000000du /* '\r' */ -#define SDLK_ESCAPE 0x0000001bu /* '\x1B' */ -#define SDLK_BACKSPACE 0x00000008u /* '\b' */ -#define SDLK_TAB 0x00000009u /* '\t' */ -#define SDLK_SPACE 0x00000020u /* ' ' */ -#define SDLK_EXCLAIM 0x00000021u /* '!' */ -#define SDLK_DBLAPOSTROPHE 0x00000022u /* '"' */ -#define SDLK_HASH 0x00000023u /* '#' */ -#define SDLK_DOLLAR 0x00000024u /* '$' */ -#define SDLK_PERCENT 0x00000025u /* '%' */ -#define SDLK_AMPERSAND 0x00000026u /* '&' */ -#define SDLK_APOSTROPHE 0x00000027u /* '\'' */ -#define SDLK_LEFTPAREN 0x00000028u /* '(' */ -#define SDLK_RIGHTPAREN 0x00000029u /* ')' */ -#define SDLK_ASTERISK 0x0000002au /* '*' */ -#define SDLK_PLUS 0x0000002bu /* '+' */ -#define SDLK_COMMA 0x0000002cu /* ',' */ -#define SDLK_MINUS 0x0000002du /* '-' */ -#define SDLK_PERIOD 0x0000002eu /* '.' */ -#define SDLK_SLASH 0x0000002fu /* '/' */ -#define SDLK_0 0x00000030u /* '0' */ -#define SDLK_1 0x00000031u /* '1' */ -#define SDLK_2 0x00000032u /* '2' */ -#define SDLK_3 0x00000033u /* '3' */ -#define SDLK_4 0x00000034u /* '4' */ -#define SDLK_5 0x00000035u /* '5' */ -#define SDLK_6 0x00000036u /* '6' */ -#define SDLK_7 0x00000037u /* '7' */ -#define SDLK_8 0x00000038u /* '8' */ -#define SDLK_9 0x00000039u /* '9' */ -#define SDLK_COLON 0x0000003au /* ':' */ -#define SDLK_SEMICOLON 0x0000003bu /* ';' */ -#define SDLK_LESS 0x0000003cu /* '<' */ -#define SDLK_EQUALS 0x0000003du /* '=' */ -#define SDLK_GREATER 0x0000003eu /* '>' */ -#define SDLK_QUESTION 0x0000003fu /* '?' */ -#define SDLK_AT 0x00000040u /* '@' */ -#define SDLK_LEFTBRACKET 0x0000005bu /* '[' */ -#define SDLK_BACKSLASH 0x0000005cu /* '\\' */ -#define SDLK_RIGHTBRACKET 0x0000005du /* ']' */ -#define SDLK_CARET 0x0000005eu /* '^' */ -#define SDLK_UNDERSCORE 0x0000005fu /* '_' */ -#define SDLK_GRAVE 0x00000060u /* '`' */ -#define SDLK_A 0x00000061u /* 'a' */ -#define SDLK_B 0x00000062u /* 'b' */ -#define SDLK_C 0x00000063u /* 'c' */ -#define SDLK_D 0x00000064u /* 'd' */ -#define SDLK_E 0x00000065u /* 'e' */ -#define SDLK_F 0x00000066u /* 'f' */ -#define SDLK_G 0x00000067u /* 'g' */ -#define SDLK_H 0x00000068u /* 'h' */ -#define SDLK_I 0x00000069u /* 'i' */ -#define SDLK_J 0x0000006au /* 'j' */ -#define SDLK_K 0x0000006bu /* 'k' */ -#define SDLK_L 0x0000006cu /* 'l' */ -#define SDLK_M 0x0000006du /* 'm' */ -#define SDLK_N 0x0000006eu /* 'n' */ -#define SDLK_O 0x0000006fu /* 'o' */ -#define SDLK_P 0x00000070u /* 'p' */ -#define SDLK_Q 0x00000071u /* 'q' */ -#define SDLK_R 0x00000072u /* 'r' */ -#define SDLK_S 0x00000073u /* 's' */ -#define SDLK_T 0x00000074u /* 't' */ -#define SDLK_U 0x00000075u /* 'u' */ -#define SDLK_V 0x00000076u /* 'v' */ -#define SDLK_W 0x00000077u /* 'w' */ -#define SDLK_X 0x00000078u /* 'x' */ -#define SDLK_Y 0x00000079u /* 'y' */ -#define SDLK_Z 0x0000007au /* 'z' */ -#define SDLK_LEFTBRACE 0x0000007bu /* '{' */ -#define SDLK_PIPE 0x0000007cu /* '|' */ -#define SDLK_RIGHTBRACE 0x0000007du /* '}' */ -#define SDLK_TILDE 0x0000007eu /* '~' */ -#define SDLK_DELETE 0x0000007fu /* '\x7F' */ -#define SDLK_PLUSMINUS 0x000000b1u /* '±' */ -#define SDLK_CAPSLOCK 0x40000039u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ -#define SDLK_F1 0x4000003au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ -#define SDLK_F2 0x4000003bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ -#define SDLK_F3 0x4000003cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ -#define SDLK_F4 0x4000003du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ -#define SDLK_F5 0x4000003eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ -#define SDLK_F6 0x4000003fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ -#define SDLK_F7 0x40000040u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ -#define SDLK_F8 0x40000041u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ -#define SDLK_F9 0x40000042u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ -#define SDLK_F10 0x40000043u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ -#define SDLK_F11 0x40000044u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ -#define SDLK_F12 0x40000045u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ -#define SDLK_PRINTSCREEN 0x40000046u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ -#define SDLK_SCROLLLOCK 0x40000047u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ -#define SDLK_PAUSE 0x40000048u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ -#define SDLK_INSERT 0x40000049u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ -#define SDLK_HOME 0x4000004au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ -#define SDLK_PAGEUP 0x4000004bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ -#define SDLK_END 0x4000004du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ -#define SDLK_PAGEDOWN 0x4000004eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ -#define SDLK_RIGHT 0x4000004fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ -#define SDLK_LEFT 0x40000050u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ -#define SDLK_DOWN 0x40000051u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ -#define SDLK_UP 0x40000052u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ -#define SDLK_NUMLOCKCLEAR 0x40000053u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ -#define SDLK_KP_DIVIDE 0x40000054u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ -#define SDLK_KP_MULTIPLY 0x40000055u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ -#define SDLK_KP_MINUS 0x40000056u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ -#define SDLK_KP_PLUS 0x40000057u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ -#define SDLK_KP_ENTER 0x40000058u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ -#define SDLK_KP_1 0x40000059u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ -#define SDLK_KP_2 0x4000005au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ -#define SDLK_KP_3 0x4000005bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ -#define SDLK_KP_4 0x4000005cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ -#define SDLK_KP_5 0x4000005du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ -#define SDLK_KP_6 0x4000005eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ -#define SDLK_KP_7 0x4000005fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ -#define SDLK_KP_8 0x40000060u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ -#define SDLK_KP_9 0x40000061u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ -#define SDLK_KP_0 0x40000062u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ -#define SDLK_KP_PERIOD 0x40000063u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ -#define SDLK_APPLICATION 0x40000065u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ -#define SDLK_POWER 0x40000066u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ -#define SDLK_KP_EQUALS 0x40000067u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ -#define SDLK_F13 0x40000068u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ -#define SDLK_F14 0x40000069u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ -#define SDLK_F15 0x4000006au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ -#define SDLK_F16 0x4000006bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ -#define SDLK_F17 0x4000006cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ -#define SDLK_F18 0x4000006du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ -#define SDLK_F19 0x4000006eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ -#define SDLK_F20 0x4000006fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ -#define SDLK_F21 0x40000070u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ -#define SDLK_F22 0x40000071u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ -#define SDLK_F23 0x40000072u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ -#define SDLK_F24 0x40000073u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ -#define SDLK_EXECUTE 0x40000074u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ -#define SDLK_HELP 0x40000075u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ -#define SDLK_MENU 0x40000076u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ -#define SDLK_SELECT 0x40000077u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ -#define SDLK_STOP 0x40000078u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ -#define SDLK_AGAIN 0x40000079u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ -#define SDLK_UNDO 0x4000007au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ -#define SDLK_CUT 0x4000007bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ -#define SDLK_COPY 0x4000007cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ -#define SDLK_PASTE 0x4000007du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ -#define SDLK_FIND 0x4000007eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ -#define SDLK_MUTE 0x4000007fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ -#define SDLK_VOLUMEUP 0x40000080u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ -#define SDLK_VOLUMEDOWN 0x40000081u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ -#define SDLK_KP_COMMA 0x40000085u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ -#define SDLK_KP_EQUALSAS400 0x40000086u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ -#define SDLK_ALTERASE 0x40000099u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ -#define SDLK_SYSREQ 0x4000009au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ -#define SDLK_CANCEL 0x4000009bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ -#define SDLK_CLEAR 0x4000009cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ -#define SDLK_PRIOR 0x4000009du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ -#define SDLK_RETURN2 0x4000009eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ -#define SDLK_SEPARATOR 0x4000009fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ -#define SDLK_OUT 0x400000a0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ -#define SDLK_OPER 0x400000a1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ -#define SDLK_CLEARAGAIN 0x400000a2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ -#define SDLK_CRSEL 0x400000a3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ -#define SDLK_EXSEL 0x400000a4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ -#define SDLK_KP_00 0x400000b0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ -#define SDLK_KP_000 0x400000b1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ -#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ -#define SDLK_DECIMALSEPARATOR 0x400000b3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ -#define SDLK_CURRENCYUNIT 0x400000b4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ -#define SDLK_CURRENCYSUBUNIT 0x400000b5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ -#define SDLK_KP_LEFTPAREN 0x400000b6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ -#define SDLK_KP_RIGHTPAREN 0x400000b7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ -#define SDLK_KP_LEFTBRACE 0x400000b8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ -#define SDLK_KP_RIGHTBRACE 0x400000b9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ -#define SDLK_KP_TAB 0x400000bau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ -#define SDLK_KP_BACKSPACE 0x400000bbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ -#define SDLK_KP_A 0x400000bcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ -#define SDLK_KP_B 0x400000bdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ -#define SDLK_KP_C 0x400000beu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ -#define SDLK_KP_D 0x400000bfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ -#define SDLK_KP_E 0x400000c0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ -#define SDLK_KP_F 0x400000c1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ -#define SDLK_KP_XOR 0x400000c2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ -#define SDLK_KP_POWER 0x400000c3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ -#define SDLK_KP_PERCENT 0x400000c4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ -#define SDLK_KP_LESS 0x400000c5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ -#define SDLK_KP_GREATER 0x400000c6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ -#define SDLK_KP_AMPERSAND 0x400000c7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ -#define SDLK_KP_DBLAMPERSAND 0x400000c8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ -#define SDLK_KP_VERTICALBAR 0x400000c9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ -#define SDLK_KP_DBLVERTICALBAR 0x400000cau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ -#define SDLK_KP_COLON 0x400000cbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ -#define SDLK_KP_HASH 0x400000ccu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ -#define SDLK_KP_SPACE 0x400000cdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ -#define SDLK_KP_AT 0x400000ceu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ -#define SDLK_KP_EXCLAM 0x400000cfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ -#define SDLK_KP_MEMSTORE 0x400000d0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ -#define SDLK_KP_MEMRECALL 0x400000d1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ -#define SDLK_KP_MEMCLEAR 0x400000d2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ -#define SDLK_KP_MEMADD 0x400000d3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ -#define SDLK_KP_MEMSUBTRACT 0x400000d4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ -#define SDLK_KP_MEMMULTIPLY 0x400000d5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ -#define SDLK_KP_MEMDIVIDE 0x400000d6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ -#define SDLK_KP_PLUSMINUS 0x400000d7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ -#define SDLK_KP_CLEAR 0x400000d8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ -#define SDLK_KP_CLEARENTRY 0x400000d9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ -#define SDLK_KP_BINARY 0x400000dau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ -#define SDLK_KP_OCTAL 0x400000dbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ -#define SDLK_KP_DECIMAL 0x400000dcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ -#define SDLK_KP_HEXADECIMAL 0x400000ddu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ -#define SDLK_LCTRL 0x400000e0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ -#define SDLK_LSHIFT 0x400000e1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ -#define SDLK_LALT 0x400000e2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ -#define SDLK_LGUI 0x400000e3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ -#define SDLK_RCTRL 0x400000e4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ -#define SDLK_RSHIFT 0x400000e5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ -#define SDLK_RALT 0x400000e6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ -#define SDLK_RGUI 0x400000e7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ -#define SDLK_MODE 0x40000101u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ -#define SDLK_SLEEP 0x40000102u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ -#define SDLK_WAKE 0x40000103u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ -#define SDLK_CHANNEL_INCREMENT 0x40000104u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ -#define SDLK_CHANNEL_DECREMENT 0x40000105u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ -#define SDLK_MEDIA_PLAY 0x40000106u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ -#define SDLK_MEDIA_PAUSE 0x40000107u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ -#define SDLK_MEDIA_RECORD 0x40000108u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ -#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ -#define SDLK_MEDIA_REWIND 0x4000010au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ -#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ -#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ -#define SDLK_MEDIA_STOP 0x4000010du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ -#define SDLK_MEDIA_EJECT 0x4000010eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ -#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ -#define SDLK_MEDIA_SELECT 0x40000110u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ -#define SDLK_AC_NEW 0x40000111u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ -#define SDLK_AC_OPEN 0x40000112u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ -#define SDLK_AC_CLOSE 0x40000113u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ -#define SDLK_AC_EXIT 0x40000114u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ -#define SDLK_AC_SAVE 0x40000115u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ -#define SDLK_AC_PRINT 0x40000116u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ -#define SDLK_AC_PROPERTIES 0x40000117u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ -#define SDLK_AC_SEARCH 0x40000118u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ -#define SDLK_AC_HOME 0x40000119u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ -#define SDLK_AC_BACK 0x4000011au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ -#define SDLK_AC_FORWARD 0x4000011bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ -#define SDLK_AC_STOP 0x4000011cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ -#define SDLK_AC_REFRESH 0x4000011du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ -#define SDLK_AC_BOOKMARKS 0x4000011eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ -#define SDLK_SOFTLEFT 0x4000011fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ -#define SDLK_SOFTRIGHT 0x40000120u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ -#define SDLK_CALL 0x40000121u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ -#define SDLK_ENDCALL 0x40000122u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_UNKNOWN 0x00000000u /**< 0 */ +#define SDLK_RETURN 0x0000000du /**< '\r' */ +#define SDLK_ESCAPE 0x0000001bu /**< '\x1B' */ +#define SDLK_BACKSPACE 0x00000008u /**< '\b' */ +#define SDLK_TAB 0x00000009u /**< '\t' */ +#define SDLK_SPACE 0x00000020u /**< ' ' */ +#define SDLK_EXCLAIM 0x00000021u /**< '!' */ +#define SDLK_DBLAPOSTROPHE 0x00000022u /**< '"' */ +#define SDLK_HASH 0x00000023u /**< '#' */ +#define SDLK_DOLLAR 0x00000024u /**< '$' */ +#define SDLK_PERCENT 0x00000025u /**< '%' */ +#define SDLK_AMPERSAND 0x00000026u /**< '&' */ +#define SDLK_APOSTROPHE 0x00000027u /**< '\'' */ +#define SDLK_LEFTPAREN 0x00000028u /**< '(' */ +#define SDLK_RIGHTPAREN 0x00000029u /**< ')' */ +#define SDLK_ASTERISK 0x0000002au /**< '*' */ +#define SDLK_PLUS 0x0000002bu /**< '+' */ +#define SDLK_COMMA 0x0000002cu /**< ',' */ +#define SDLK_MINUS 0x0000002du /**< '-' */ +#define SDLK_PERIOD 0x0000002eu /**< '.' */ +#define SDLK_SLASH 0x0000002fu /**< '/' */ +#define SDLK_0 0x00000030u /**< '0' */ +#define SDLK_1 0x00000031u /**< '1' */ +#define SDLK_2 0x00000032u /**< '2' */ +#define SDLK_3 0x00000033u /**< '3' */ +#define SDLK_4 0x00000034u /**< '4' */ +#define SDLK_5 0x00000035u /**< '5' */ +#define SDLK_6 0x00000036u /**< '6' */ +#define SDLK_7 0x00000037u /**< '7' */ +#define SDLK_8 0x00000038u /**< '8' */ +#define SDLK_9 0x00000039u /**< '9' */ +#define SDLK_COLON 0x0000003au /**< ':' */ +#define SDLK_SEMICOLON 0x0000003bu /**< ';' */ +#define SDLK_LESS 0x0000003cu /**< '<' */ +#define SDLK_EQUALS 0x0000003du /**< '=' */ +#define SDLK_GREATER 0x0000003eu /**< '>' */ +#define SDLK_QUESTION 0x0000003fu /**< '?' */ +#define SDLK_AT 0x00000040u /**< '@' */ +#define SDLK_LEFTBRACKET 0x0000005bu /**< '[' */ +#define SDLK_BACKSLASH 0x0000005cu /**< '\\' */ +#define SDLK_RIGHTBRACKET 0x0000005du /**< ']' */ +#define SDLK_CARET 0x0000005eu /**< '^' */ +#define SDLK_UNDERSCORE 0x0000005fu /**< '_' */ +#define SDLK_GRAVE 0x00000060u /**< '`' */ +#define SDLK_A 0x00000061u /**< 'a' */ +#define SDLK_B 0x00000062u /**< 'b' */ +#define SDLK_C 0x00000063u /**< 'c' */ +#define SDLK_D 0x00000064u /**< 'd' */ +#define SDLK_E 0x00000065u /**< 'e' */ +#define SDLK_F 0x00000066u /**< 'f' */ +#define SDLK_G 0x00000067u /**< 'g' */ +#define SDLK_H 0x00000068u /**< 'h' */ +#define SDLK_I 0x00000069u /**< 'i' */ +#define SDLK_J 0x0000006au /**< 'j' */ +#define SDLK_K 0x0000006bu /**< 'k' */ +#define SDLK_L 0x0000006cu /**< 'l' */ +#define SDLK_M 0x0000006du /**< 'm' */ +#define SDLK_N 0x0000006eu /**< 'n' */ +#define SDLK_O 0x0000006fu /**< 'o' */ +#define SDLK_P 0x00000070u /**< 'p' */ +#define SDLK_Q 0x00000071u /**< 'q' */ +#define SDLK_R 0x00000072u /**< 'r' */ +#define SDLK_S 0x00000073u /**< 's' */ +#define SDLK_T 0x00000074u /**< 't' */ +#define SDLK_U 0x00000075u /**< 'u' */ +#define SDLK_V 0x00000076u /**< 'v' */ +#define SDLK_W 0x00000077u /**< 'w' */ +#define SDLK_X 0x00000078u /**< 'x' */ +#define SDLK_Y 0x00000079u /**< 'y' */ +#define SDLK_Z 0x0000007au /**< 'z' */ +#define SDLK_LEFTBRACE 0x0000007bu /**< '{' */ +#define SDLK_PIPE 0x0000007cu /**< '|' */ +#define SDLK_RIGHTBRACE 0x0000007du /**< '}' */ +#define SDLK_TILDE 0x0000007eu /**< '~' */ +#define SDLK_DELETE 0x0000007fu /**< '\x7F' */ +#define SDLK_PLUSMINUS 0x000000b1u /**< '\xB1' */ +#define SDLK_CAPSLOCK 0x40000039u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ +#define SDLK_F1 0x4000003au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ +#define SDLK_F2 0x4000003bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ +#define SDLK_F3 0x4000003cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ +#define SDLK_F4 0x4000003du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ +#define SDLK_F5 0x4000003eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ +#define SDLK_F6 0x4000003fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ +#define SDLK_F7 0x40000040u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ +#define SDLK_F8 0x40000041u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ +#define SDLK_F9 0x40000042u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ +#define SDLK_F10 0x40000043u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ +#define SDLK_F11 0x40000044u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ +#define SDLK_F12 0x40000045u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ +#define SDLK_PRINTSCREEN 0x40000046u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ +#define SDLK_SCROLLLOCK 0x40000047u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ +#define SDLK_PAUSE 0x40000048u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ +#define SDLK_INSERT 0x40000049u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ +#define SDLK_HOME 0x4000004au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ +#define SDLK_PAGEUP 0x4000004bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ +#define SDLK_END 0x4000004du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ +#define SDLK_PAGEDOWN 0x4000004eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ +#define SDLK_RIGHT 0x4000004fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ +#define SDLK_LEFT 0x40000050u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ +#define SDLK_DOWN 0x40000051u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ +#define SDLK_UP 0x40000052u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ +#define SDLK_NUMLOCKCLEAR 0x40000053u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ +#define SDLK_KP_DIVIDE 0x40000054u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ +#define SDLK_KP_MULTIPLY 0x40000055u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ +#define SDLK_KP_MINUS 0x40000056u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ +#define SDLK_KP_PLUS 0x40000057u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ +#define SDLK_KP_ENTER 0x40000058u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ +#define SDLK_KP_1 0x40000059u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ +#define SDLK_KP_2 0x4000005au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ +#define SDLK_KP_3 0x4000005bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ +#define SDLK_KP_4 0x4000005cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ +#define SDLK_KP_5 0x4000005du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ +#define SDLK_KP_6 0x4000005eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ +#define SDLK_KP_7 0x4000005fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ +#define SDLK_KP_8 0x40000060u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ +#define SDLK_KP_9 0x40000061u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ +#define SDLK_KP_0 0x40000062u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ +#define SDLK_KP_PERIOD 0x40000063u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ +#define SDLK_APPLICATION 0x40000065u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ +#define SDLK_POWER 0x40000066u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ +#define SDLK_KP_EQUALS 0x40000067u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ +#define SDLK_F13 0x40000068u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ +#define SDLK_F14 0x40000069u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ +#define SDLK_F15 0x4000006au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ +#define SDLK_F16 0x4000006bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ +#define SDLK_F17 0x4000006cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ +#define SDLK_F18 0x4000006du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ +#define SDLK_F19 0x4000006eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ +#define SDLK_F20 0x4000006fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ +#define SDLK_F21 0x40000070u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ +#define SDLK_F22 0x40000071u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ +#define SDLK_F23 0x40000072u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ +#define SDLK_F24 0x40000073u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ +#define SDLK_EXECUTE 0x40000074u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ +#define SDLK_HELP 0x40000075u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ +#define SDLK_MENU 0x40000076u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ +#define SDLK_SELECT 0x40000077u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ +#define SDLK_STOP 0x40000078u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ +#define SDLK_AGAIN 0x40000079u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ +#define SDLK_UNDO 0x4000007au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ +#define SDLK_CUT 0x4000007bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ +#define SDLK_COPY 0x4000007cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ +#define SDLK_PASTE 0x4000007du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ +#define SDLK_FIND 0x4000007eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ +#define SDLK_MUTE 0x4000007fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ +#define SDLK_VOLUMEUP 0x40000080u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ +#define SDLK_VOLUMEDOWN 0x40000081u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ +#define SDLK_KP_COMMA 0x40000085u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ +#define SDLK_KP_EQUALSAS400 0x40000086u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ +#define SDLK_ALTERASE 0x40000099u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ +#define SDLK_SYSREQ 0x4000009au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ +#define SDLK_CANCEL 0x4000009bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ +#define SDLK_CLEAR 0x4000009cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ +#define SDLK_PRIOR 0x4000009du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ +#define SDLK_RETURN2 0x4000009eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ +#define SDLK_SEPARATOR 0x4000009fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ +#define SDLK_OUT 0x400000a0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ +#define SDLK_OPER 0x400000a1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ +#define SDLK_CLEARAGAIN 0x400000a2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ +#define SDLK_CRSEL 0x400000a3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ +#define SDLK_EXSEL 0x400000a4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ +#define SDLK_KP_00 0x400000b0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ +#define SDLK_KP_000 0x400000b1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ +#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ +#define SDLK_DECIMALSEPARATOR 0x400000b3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ +#define SDLK_CURRENCYUNIT 0x400000b4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ +#define SDLK_CURRENCYSUBUNIT 0x400000b5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ +#define SDLK_KP_LEFTPAREN 0x400000b6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ +#define SDLK_KP_RIGHTPAREN 0x400000b7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ +#define SDLK_KP_LEFTBRACE 0x400000b8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ +#define SDLK_KP_RIGHTBRACE 0x400000b9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ +#define SDLK_KP_TAB 0x400000bau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ +#define SDLK_KP_BACKSPACE 0x400000bbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ +#define SDLK_KP_A 0x400000bcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ +#define SDLK_KP_B 0x400000bdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ +#define SDLK_KP_C 0x400000beu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ +#define SDLK_KP_D 0x400000bfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ +#define SDLK_KP_E 0x400000c0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ +#define SDLK_KP_F 0x400000c1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ +#define SDLK_KP_XOR 0x400000c2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ +#define SDLK_KP_POWER 0x400000c3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ +#define SDLK_KP_PERCENT 0x400000c4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ +#define SDLK_KP_LESS 0x400000c5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ +#define SDLK_KP_GREATER 0x400000c6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ +#define SDLK_KP_AMPERSAND 0x400000c7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ +#define SDLK_KP_DBLAMPERSAND 0x400000c8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ +#define SDLK_KP_VERTICALBAR 0x400000c9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ +#define SDLK_KP_DBLVERTICALBAR 0x400000cau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ +#define SDLK_KP_COLON 0x400000cbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ +#define SDLK_KP_HASH 0x400000ccu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ +#define SDLK_KP_SPACE 0x400000cdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ +#define SDLK_KP_AT 0x400000ceu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ +#define SDLK_KP_EXCLAM 0x400000cfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ +#define SDLK_KP_MEMSTORE 0x400000d0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ +#define SDLK_KP_MEMRECALL 0x400000d1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ +#define SDLK_KP_MEMCLEAR 0x400000d2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ +#define SDLK_KP_MEMADD 0x400000d3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ +#define SDLK_KP_MEMSUBTRACT 0x400000d4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ +#define SDLK_KP_MEMMULTIPLY 0x400000d5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ +#define SDLK_KP_MEMDIVIDE 0x400000d6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ +#define SDLK_KP_PLUSMINUS 0x400000d7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ +#define SDLK_KP_CLEAR 0x400000d8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ +#define SDLK_KP_CLEARENTRY 0x400000d9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ +#define SDLK_KP_BINARY 0x400000dau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ +#define SDLK_KP_OCTAL 0x400000dbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ +#define SDLK_KP_DECIMAL 0x400000dcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ +#define SDLK_KP_HEXADECIMAL 0x400000ddu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ +#define SDLK_LCTRL 0x400000e0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ +#define SDLK_LSHIFT 0x400000e1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ +#define SDLK_LALT 0x400000e2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ +#define SDLK_LGUI 0x400000e3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ +#define SDLK_RCTRL 0x400000e4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ +#define SDLK_RSHIFT 0x400000e5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ +#define SDLK_RALT 0x400000e6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ +#define SDLK_RGUI 0x400000e7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ +#define SDLK_MODE 0x40000101u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ +#define SDLK_SLEEP 0x40000102u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ +#define SDLK_WAKE 0x40000103u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ +#define SDLK_CHANNEL_INCREMENT 0x40000104u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ +#define SDLK_CHANNEL_DECREMENT 0x40000105u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ +#define SDLK_MEDIA_PLAY 0x40000106u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ +#define SDLK_MEDIA_PAUSE 0x40000107u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ +#define SDLK_MEDIA_RECORD 0x40000108u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ +#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ +#define SDLK_MEDIA_REWIND 0x4000010au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ +#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ +#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ +#define SDLK_MEDIA_STOP 0x4000010du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ +#define SDLK_MEDIA_EJECT 0x4000010eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ +#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ +#define SDLK_MEDIA_SELECT 0x40000110u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ +#define SDLK_AC_NEW 0x40000111u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ +#define SDLK_AC_OPEN 0x40000112u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ +#define SDLK_AC_CLOSE 0x40000113u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ +#define SDLK_AC_EXIT 0x40000114u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ +#define SDLK_AC_SAVE 0x40000115u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ +#define SDLK_AC_PRINT 0x40000116u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ +#define SDLK_AC_PROPERTIES 0x40000117u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ +#define SDLK_AC_SEARCH 0x40000118u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ +#define SDLK_AC_HOME 0x40000119u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ +#define SDLK_AC_BACK 0x4000011au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ +#define SDLK_AC_FORWARD 0x4000011bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ +#define SDLK_AC_STOP 0x4000011cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ +#define SDLK_AC_REFRESH 0x4000011du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ +#define SDLK_AC_BOOKMARKS 0x4000011eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ +#define SDLK_SOFTLEFT 0x4000011fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ +#define SDLK_SOFTRIGHT 0x40000120u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ +#define SDLK_CALL 0x40000121u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ +#define SDLK_ENDCALL 0x40000122u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_LEFT_TAB 0x20000001u /**< Extended key Left Tab */ +#define SDLK_LEVEL5_SHIFT 0x20000002u /**< Extended key Level 5 Shift */ +#define SDLK_MULTI_KEY_COMPOSE 0x20000003u /**< Extended key Multi-key Compose */ +#define SDLK_LMETA 0x20000004u /**< Extended key Left Meta */ +#define SDLK_RMETA 0x20000005u /**< Extended key Right Meta */ +#define SDLK_LHYPER 0x20000006u /**< Extended key Left Hyper */ +#define SDLK_RHYPER 0x20000007u /**< Extended key Right Hyper */ /** * Valid key modifiers (possibly OR'd together). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint16 SDL_Keymod; #define SDL_KMOD_NONE 0x0000u /**< no modifier is applicable. */ #define SDL_KMOD_LSHIFT 0x0001u /**< the left Shift key is down. */ #define SDL_KMOD_RSHIFT 0x0002u /**< the right Shift key is down. */ +#define SDL_KMOD_LEVEL5 0x0004u /**< the Level 5 Shift key is down. */ #define SDL_KMOD_LCTRL 0x0040u /**< the left Ctrl (Control) key is down. */ #define SDL_KMOD_RCTRL 0x0080u /**< the right Ctrl (Control) key is down. */ #define SDL_KMOD_LALT 0x0100u /**< the left Alt key is down. */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_loadso.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_loadso.h index ab34a38..f8649d7 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_loadso.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_loadso.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ * * System-dependent library loading routines. * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * * Some things to keep in mind: * * - These functions only work on C function names. Other languages may have @@ -38,6 +46,11 @@ * not defined whether or not it goes into the global symbol namespace for * the application. If it does and it conflicts with symbols in your code or * other shared libraries, you will not get the results you expect. :) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that pointer after the library unloads. */ #ifndef SDL_loadso_h_ @@ -52,6 +65,17 @@ extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * @@ -59,12 +83,14 @@ extern "C" { * \returns an opaque pointer to the object handle or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -86,22 +112,29 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); * \returns a pointer to the function or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_locale.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_locale.h index 85d7750..902843e 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_locale.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_locale.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategoryLocale * * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. */ #ifndef SDL_locale_h @@ -47,7 +53,7 @@ extern "C" { * would be "en"), and the country, if not NULL, will be an ISO-3166 country * code (so Canada would be "CA"). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPreferredLocales */ @@ -96,7 +102,7 @@ typedef struct SDL_Locale * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_log.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_log.h index deda238..a56476c 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_log.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_log.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,7 @@ /** * # CategoryLog * - * Simple log messages with priorities and categories. A message’s + * Simple log messages with priorities and categories. A message's * SDL_LogPriority signifies how important the message is. A message's * SDL_LogCategory signifies from what domain it belongs to. Every category * has a minimum priority specified: when a message belongs to that category, @@ -76,7 +76,7 @@ extern "C" { * level, the assert category is enabled at the WARN level, test is enabled at * the VERBOSE level and all other categories are enabled at the ERROR level. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogCategory { @@ -87,12 +87,11 @@ typedef enum SDL_LogCategory SDL_LOG_CATEGORY_AUDIO, SDL_LOG_CATEGORY_VIDEO, SDL_LOG_CATEGORY_RENDER, - SDL_LOG_CATEGORY_GPU, SDL_LOG_CATEGORY_INPUT, SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, SDL_LOG_CATEGORY_RESERVED2, SDL_LOG_CATEGORY_RESERVED3, SDL_LOG_CATEGORY_RESERVED4, @@ -117,17 +116,19 @@ typedef enum SDL_LogCategory /** * The predefined log priorities * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogPriority { - SDL_LOG_PRIORITY_VERBOSE = 1, + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, SDL_LOG_PRIORITY_DEBUG, SDL_LOG_PRIORITY_INFO, SDL_LOG_PRIORITY_WARN, SDL_LOG_PRIORITY_ERROR, SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES + SDL_LOG_PRIORITY_COUNT } SDL_LogPriority; @@ -136,7 +137,9 @@ typedef enum SDL_LogPriority * * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriority @@ -149,14 +152,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); * \param category the category to assign a priority to. * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetLogPriority * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriorities */ -extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, - SDL_LogPriority priority); +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); /** * Get the priority of a particular log category. @@ -164,7 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, * \param category the category to query. * \returns the SDL_LogPriority for the requested category. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriority */ @@ -175,7 +181,9 @@ extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); * * This is called by SDL_Quit(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority @@ -192,15 +200,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); * \param priority the SDL_LogPriority to modify. * \param prefix the prefix to use for that log priority, or NULL to use no * prefix. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); /** * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. @@ -209,7 +219,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \param ... additional parameters matching % tokens in the `fmt` string, if * any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LogCritical * \sa SDL_LogDebug @@ -217,11 +229,37 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * @@ -230,7 +268,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -251,7 +291,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -259,6 +301,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -272,7 +315,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -280,6 +325,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogError * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -293,7 +339,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -302,6 +350,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose */ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); @@ -314,7 +363,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -322,6 +373,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -335,7 +387,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogDebug @@ -343,6 +397,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -357,7 +412,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -365,6 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -380,7 +438,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \param fmt a printf() style message format string. * \param ap a variable argument list. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -388,6 +448,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessage + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -398,7 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, /** * The prototype for the log output callback function. * - * This function is called by SDL when there is new text to be logged. + * This function is called by SDL when there is new text to be logged. A mutex + * is held so that this function is never called by more than one thread at + * once. * * \param userdata what was passed as `userdata` to * SDL_SetLogOutputFunction(). @@ -406,10 +469,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, * \param priority the priority of the message. * \param message the message being output. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void); + /** * Get the current log output function. * @@ -418,8 +495,11 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * \param userdata a pointer filled in with the pointer that is passed to * `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_SetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata); @@ -430,8 +510,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction * \param callback an SDL_LogOutputFunction to call instead of the default. * \param userdata a pointer that is passed to `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_GetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main.h index de3c187..2e7a2eb 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,13 +22,29 @@ /** * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() if necessary so that it is called by SDL. * - * For details on how SDL_main works, and how to use it, please refer to: + * In order to make this consistent on all platforms, the application's main() + * should look like this: + * + * ```c + * int main(int argc, char *argv[]) + * { + * } + * ``` + * + * SDL will take care of platform specific details on how it gets called. + * + * This is also where an app can be configured to use the main callbacks, via + * the SDL_MAIN_USE_CALLBACKS macro. + * + * This is a "single-header library," which is to say that including this + * header inserts code into your program, and you should only include it once + * in most cases. SDL.h does not include this header automatically. + * + * For more information, see: * * https://wiki.libsdl.org/SDL3/README/main-functions - * - * (or docs/README-main-functions.md in the SDL source tree) */ #ifndef SDL_main_h_ @@ -39,8 +55,96 @@ #include #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Inform SDL that the app is providing an entry point instead of SDL. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide the + * proper entry point for the platform, and all the other magic details + * needed, like manually calling SDL_SetMainReady. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + */ +#define SDL_MAIN_HANDLED 1 + +/** + * Inform SDL to use the main callbacks instead of main. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide + * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and + * SDL_AppQuit. The app should not provide a `main` function in this case, and + * doing so will likely cause the build to fail. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + * \sa SDL_AppIterate + * \sa SDL_AppQuit + */ +#define SDL_MAIN_USE_CALLBACKS 1 + +/** + * Defined if the target platform offers a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if available, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_AVAILABLE + +/** + * Defined if the target platform _requires_ a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if required, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_NEEDED + +#endif + +#if defined(__has_include) + #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h") + #define SDL_PLATFORM_PRIVATE_MAIN + #endif +#endif + #ifndef SDL_MAIN_HANDLED - #ifdef SDL_PLATFORM_WIN32 + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_private.h" + + #elif defined(SDL_PLATFORM_WIN32) /* On Windows SDL provides WinMain(), which parses the command line and passes the arguments to your main function. @@ -48,20 +152,6 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_WINRT) - /* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - 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 ` - 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 - #elif defined(SDL_PLATFORM_GDK) /* On GDK, SDL provides a main function that initializes the game runtime. @@ -91,8 +181,14 @@ */ #define SDL_MAIN_NEEDED - /* We need to export SDL_main so it can be launched from Java */ - #define SDLMAIN_DECLSPEC SDL_DECLSPEC + /* As this is launched from Java, the real entry point (main() function) + is outside of the the binary built from this code. + This define makes sure that, unlike on other platforms, SDL_main.h + and SDL_main_impl.h export an `SDL_main()` function (to be called + from Java), but don't implement a native `int main(int argc, char* argv[])` + or similar. + */ + #define SDL_MAIN_EXPORTED #elif defined(SDL_PLATFORM_EMSCRIPTEN) /* On Emscripten, SDL provides a main function that converts URL @@ -129,60 +225,36 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_NGAGE) - /* - TODO: not sure if it should be SDL_MAIN_NEEDED, in SDL2 ngage had a - main implementation, but wasn't mentioned in SDL_main.h - */ - #define SDL_MAIN_AVAILABLE - #endif #endif /* SDL_MAIN_HANDLED */ -#ifndef SDLMAIN_DECLSPEC -#define SDLMAIN_DECLSPEC -#endif - -/** - * \file SDL_main.h - * - * The application's main() function must be called with C linkage, - * and should be declared like this: - * - * ```c - * #ifdef __cplusplus - * extern "C" - * #endif - * int main(int argc, char *argv[]) - * { - * } - * ``` - */ #ifdef SDL_WIKI_DOCUMENTATION_SECTION /** - * Inform SDL to use the main callbacks instead of main. + * A macro to tag a main entry point function as exported. * - * SDL does not define this macro, but will check if it is defined when - * including `SDL_main.h`. If defined, SDL will expect the app to provide - * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and - * SDL_AppQuit. The app should not provide a `main` function in this case, and - * doing so will likely cause the build to fail. + * Most platforms don't need this, and the macro will be defined to nothing. + * Some, like Android, keep the entry points in a shared library and need to + * explicitly export the symbols. * - * Please see [README/main-functions](README/main-functions), (or - * docs/README-main-functions.md in the source tree) for a more detailed - * explanation. + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. * - * \since This macro is used by the headers since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit + * \sa SDL_DECLSPEC */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif +#define SDLMAIN_DECLSPEC + +#elif defined(SDL_MAIN_EXPORTED) +/* We need to export SDL_main so it can be launched from external code, + like SDLActivity.java on Android */ +#define SDLMAIN_DECLSPEC SDL_DECLSPEC +#else +/* usually this is empty */ +#define SDLMAIN_DECLSPEC +#endif /* SDL_MAIN_EXPORTED */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main @@ -248,6 +320,8 @@ extern "C" { * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code * that reports success to the platform. * + * This function is called by SDL on the main thread. + * * \param appstate a place where the app can optionally store a pointer for * future use. * \param argc the standard ANSI C main's argc; number of elements in `argv`. @@ -256,9 +330,7 @@ extern "C" { * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppIterate * \sa SDL_AppEvent @@ -301,13 +373,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int a * SDL_AppQuit and terminates with an exit code that reports success to the * platform. * + * This function is called by SDL on the main thread. + * * \param appstate an optional pointer, provided by the app in SDL_AppInit. * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with SDL_AppEvent() + * for events not pushed on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppEvent @@ -320,15 +395,15 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a * standard "main" function, you should not supply this. * - * This function is called as needed by SDL after SDL_AppInit returns 0; It is - * called once for each new event. + * This function is called as needed by SDL after SDL_AppInit returns + * SDL_APP_CONTINUE. It is called once for each new event. * * There is (currently) no guarantee about what thread this will be called * from; whatever thread pushes an event onto SDL's queue will trigger this * function. SDL is responsible for pumping the event queue between each call * to SDL_AppIterate, so in normal operation one should only get events in a * serial fashion, but be careful if you have a thread that explicitly calls - * SDL_PushEvent. + * SDL_PushEvent. SDL itself will push events to the queue on the main thread. * * Events sent to this function are not owned by the app; if you need to save * the data, you should copy it. @@ -352,14 +427,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with + * SDL_AppIterate() or SDL_AppQuit() for events not pushed from + * the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppIterate */ -extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); /** * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -385,15 +462,19 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const * function call is the last time this pointer will be provided, so any * resources to it should be cleaned up here. * + * This function is called by SDL on the main thread. + * * \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. + * \threadsafety SDL_AppEvent() may get called concurrently with this function + * if other threads that push events are still active. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.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 */ @@ -407,7 +488,7 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate); * program completion, and small non-zero values are considered * errors. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); @@ -440,7 +521,7 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); * * \threadsafety This is the program entry point. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); @@ -453,7 +534,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); * will not be changed it is necessary to define SDL_MAIN_HANDLED before * including SDL.h. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init */ @@ -485,7 +566,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); * \threadsafety Generally this is called once, near startup, from the * process's initial thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved); @@ -512,12 +593,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func * \threadsafety It is not safe to call this anywhere except as the only * function call in SDL_main. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) /** * Register a win32 window class for SDL's use. @@ -538,12 +619,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * what is specified here. * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL * will use `GetModuleHandle(NULL)` instead. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); /** * Deregister the win32 window class from an SDL_RegisterApp call. @@ -558,23 +639,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 st * deregistered when the registration counter in SDL_RegisterApp decrements to * zero through calls to this function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ - -#ifdef SDL_PLATFORM_GDK +#endif /* defined(SDL_PLATFORM_WINDOWS) */ /** * Callback from the application to let the suspend continue. * - * \since This function is available since SDL 3.0.0. + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); -#endif /* SDL_PLATFORM_GDK */ - #ifdef __cplusplus } #endif @@ -583,29 +663,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) /* include header-only SDL_main implementations */ - #if defined(SDL_MAIN_USE_CALLBACKS) \ - || defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ - || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) \ - || defined(SDL_PLATFORM_EMSCRIPTEN) - + #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) /* platforms which main (-equivalent) can be implemented in plain C */ #include - - #elif defined(SDL_PLATFORM_WINRT) /* C++ platforms */ - #ifdef __cplusplus - #include - #else - /* Note: to get rid of the following warning, you can #define SDL_MAIN_NOIMPL before including SDL_main.h - * in your C sourcefile that contains the standard main. Do *not* use SDL_MAIN_HANDLED for that, then SDL_main won't find your main()! - */ - #ifdef _MSC_VER - #pragma message("Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C (then continue including SDL_main.h there!) and create a fresh .cpp file that only contains #include ") - #elif defined(__GNUC__) /* gcc, clang, mingw and compatible are matched by this and have #warning */ - #warning "Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C and create a fresh .cpp file that only contains #include " - #endif /* __GNUC__ */ - #endif /* __cplusplus */ - - #endif /* C++ platforms like SDL_PLATFORM_WINRT etc */ + #endif #endif #endif /* SDL_main_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main_impl.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main_impl.h index ad122df..14ebb42 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main_impl.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_main_impl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,7 +29,7 @@ #endif /* if someone wants to include SDL_main.h but doesn't want the main handing magic, - (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first + (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first. SDL_MAIN_NOIMPL is for SDL-internal usage (only affects implementation, not definition of SDL_MAIN_AVAILABLE etc in SDL_main.h) and if the user wants to have the SDL_main implementation (from this header) in another source file @@ -64,10 +64,15 @@ #endif /* SDL_MAIN_USE_CALLBACKS */ - /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */ - #if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) + /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point, + unless the real entry point needs to be somewhere else entirely, like Android where it's in Java code */ + #if (!defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)) && !defined(SDL_MAIN_EXPORTED) - #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_impl_private.h" + + #elif defined(SDL_PLATFORM_WINDOWS) /* these defines/typedefs are needed for the WinMain() definition */ #ifndef WINAPI @@ -82,7 +87,7 @@ #if defined(_MSC_VER) && !defined(SDL_PLATFORM_GDK) /* This is where execution begins [console apps] */ - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int wmain(int argc, wchar_t *wargv[], wchar_t *wenvp) { (void)argc; @@ -107,7 +112,7 @@ extern "C" { #endif - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw) #else /* ANSI */ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw) @@ -124,83 +129,7 @@ } /* extern "C" */ #endif - /* end of SDL_PLATFORM_WIN32 and SDL_PLATFORM_GDK impls */ - - #elif defined(SDL_PLATFORM_WINRT) - - /* WinRT main based on SDL_winrt_main_NonXAML.cpp, placed in the public domain by David Ludwig 3/13/14 */ - - #include - - /* At least one file in any SDL/WinRT app appears to require compilation - with C++/CX, otherwise a Windows Metadata file won't get created, and - an APPX0702 build error can appear shortly after linking. - - The following set of preprocessor code forces this file to be compiled - as C++/CX, which appears to cause Visual C++ 2012's build tools to - create this .winmd file, and will help allow builds of SDL/WinRT apps - to proceed without error. - - If other files in an app's project enable C++/CX compilation, then it might - be possible for the .cpp file including SDL_main.h to be compiled without /ZW, - for Visual C++'s build tools to create a winmd file, and for the app to - build without APPX0702 errors. In this case, if - SDL_WINRT_METADATA_FILE_AVAILABLE is defined as a C/C++ macro, then - the #error (to force C++/CX compilation) will be disabled. - - Please note that /ZW can be specified on a file-by-file basis. To do this, - right click on the file in Visual C++, click Properties, then change the - setting through the dialog that comes up. - */ - #ifndef SDL_WINRT_METADATA_FILE_AVAILABLE - #if !defined(__cplusplus) || (!defined(__cplusplus_winrt) && _MSVC_LANG < 202002L) - #error The C++ file that includes SDL_main.h must be compiled as C++ code with /ZW, otherwise build errors due to missing .winmd files can occur. - #endif - #endif - - /* Prevent MSVC++ from warning about threading models when defining our - custom WinMain. The threading model will instead be set via a direct - call to Windows::Foundation::Initialize (rather than via an attributed - function). - - To note, this warning (C4447) does not seem to come up unless this file - is compiled with C++/CX enabled (via the /ZW compiler flag). - */ - #ifdef _MSC_VER - #pragma warning(disable : 4447) - /* Make sure the function to initialize the Windows Runtime gets linked in. */ - #pragma comment(lib, "runtimeobject.lib") - #endif - - #ifdef __cplusplus - extern "C" { - #endif - int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int) - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - #if _MSVC_LANG >= 202002L - int main(int argc, char** argv) { - return SDL_RunApp(argc, argv, SDL_main, NULL); - } - #endif - #ifdef __cplusplus - } /* extern "C" */ - #endif - - /* end of WinRT impl */ - - #elif defined(SDL_PLATFORM_NGAGE) - /* same typedef as in ngage SDKs e32def.h */ - typedef signed int TInt; - /* TODO: if it turns out that this only works when built as C++, - move SDL_PLATFORM_NGAGE into the C++ section in SDL_main.h */ - TInt E32Main() - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - - /* end of SDL_PLATFORM_NGAGE impl */ + /* end of SDL_PLATFORM_WINDOWS impls */ #else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ int main(int argc, char *argv[]) diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_messagebox.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_messagebox.h index c626b22..365ae36 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_messagebox.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_messagebox.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryMessagebox * - * Message box support routines. + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. */ #ifndef SDL_messagebox_h_ @@ -39,11 +50,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. + * Message box flags. * * If supported will display warning icon, etc. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxFlags; @@ -56,7 +67,7 @@ typedef Uint32 SDL_MessageBoxFlags; /** * SDL_MessageBoxButtonData flags. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxButtonFlags; @@ -66,7 +77,7 @@ typedef Uint32 SDL_MessageBoxButtonFlags; /** * Individual button data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxButtonData { @@ -78,7 +89,7 @@ typedef struct SDL_MessageBoxButtonData /** * RGB value used in a message box color scheme * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColor { @@ -96,23 +107,23 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX /**< Size of the colors array of SDL_MessageBoxColorScheme. */ + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** * A set of colors to use for message box dialogs * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** * MessageBox structure containing title, text, window, etc. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxData { @@ -154,14 +165,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowSimpleMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -193,17 +204,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData * to stderr if you can. * * \param flags an SDL_MessageBoxFlags value. - * \param title uTF-8 title text. - * \param message uTF-8 message text. + * \param title UTF-8 title text. + * \param message UTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_metal.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_metal.h index 7c9aece..14b1bc8 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_metal.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_metal.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,10 @@ * # CategoryMetal * * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. */ #ifndef SDL_metal_h_ @@ -39,7 +43,7 @@ extern "C" { /** * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_MetalView; @@ -61,7 +65,7 @@ typedef void *SDL_MetalView; * \param window the window. * \returns handle NSView or UIView. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_DestroyView * \sa SDL_Metal_GetLayer @@ -76,7 +80,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *windo * * \param view the SDL_MetalView object. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ @@ -88,7 +92,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); * \param view the SDL_MetalView object. * \returns a pointer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_misc.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_misc.h index 23317e0..3dd6fcd 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_misc.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_misc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -62,12 +62,12 @@ extern "C" { * * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mouse.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mouse.h index 90c8560..18856e2 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mouse.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mouse.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,36 @@ /** * # CategoryMouse * - * SDL mouse handling. + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. */ #ifndef SDL_mouse_h_ @@ -30,6 +59,7 @@ #include #include +#include #include #include @@ -46,7 +76,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MouseID; @@ -55,14 +85,14 @@ typedef Uint32 SDL_MouseID; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Cursor SDL_Cursor; /** * Cursor types for SDL_CreateSystemCursor(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemCursor { @@ -86,13 +116,13 @@ typedef enum SDL_SystemCursor SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ - SDL_NUM_SYSTEM_CURSORS + SDL_SYSTEM_CURSOR_COUNT } SDL_SystemCursor; /** * Scroll direction types for the Scroll event * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MouseWheelDirection { @@ -109,7 +139,7 @@ typedef enum SDL_MouseWheelDirection * - Button 4: Side mouse button 1 * - Button 5: Side mouse button 2 * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetMouseState * \sa SDL_GetGlobalMouseState @@ -123,12 +153,12 @@ typedef Uint32 SDL_MouseButtonFlags; #define SDL_BUTTON_X1 4 #define SDL_BUTTON_X2 5 -#define SDL_BUTTON(X) (1u << ((X)-1)) -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) /* Function prototypes */ @@ -136,13 +166,15 @@ typedef Uint32 SDL_MouseButtonFlags; /** * Return whether a mouse is currently connected. * - * \returns SDL_TRUE if a mouse is connected, SDL_FALSE otherwise. + * \returns true if a mouse is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); /** * Get a list of currently connected mice. @@ -158,7 +190,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseNameForID * \sa SDL_HasMouse @@ -174,7 +208,9 @@ extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count); * \returns the name of the selected mouse, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ @@ -185,26 +221,39 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta * * \returns the window with mouse focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); /** - * Retrieve the current state of the mouse. + * Query SDL's cache for the synchronous mouse button state and the + * window-relative SDL-cursor position. * - * The current button state is returned as a button bitmask, which can be - * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse cursor position relative to the focus window. You can pass NULL for - * either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x the x coordinate of the mouse cursor position relative to the - * focus window. - * \param y the y coordinate of the mouse cursor position relative to the - * focus window. - * \returns a 32-bit button bitmask of the current button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the focused window. + * + * In Relative Mode, the SDL-cursor's position usually contradicts the + * platform-cursor's position as manually calculated from + * SDL_GetGlobalMouseState() and SDL_GetWindowPosition. + * + * \param x a pointer to receive the SDL-cursor's x-position from the focused + * window's top left corner, can be NULL if unused. + * \param y a pointer to receive the SDL-cursor's y-position from the focused + * window's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState * \sa SDL_GetRelativeMouseState @@ -212,51 +261,74 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y); /** - * Get the current state of the mouse in relation to the desktop. + * Query the platform for the asynchronous mouse button state and the + * desktop-relative platform-cursor position. * - * This works similarly to SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if you - * need to track the mouse outside of a specific window and SDL_CaptureMouse() - * doesn't fit your needs. For example, it could be useful if you need to - * track the mouse while dragging a window, where coordinates relative to a - * window might not be in sync at all times. + * This function immediately queries the platform for the most recent + * asynchronous state, more costly than retrieving SDL's cached state in + * SDL_GetMouseState(). * - * Note: SDL_GetMouseState() returns the mouse position as SDL understands it - * from the last pump of the event queue. This function, however, queries the - * OS for the current mouse position, and as such, might be a slightly less - * efficient function. Unless you know what you're doing and have a good - * reason to use this function, you probably want SDL_GetMouseState() instead. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the desktop. * - * \param x filled in with the current X coord relative to the desktop; can be - * NULL. - * \param y filled in with the current Y coord relative to the desktop; can be - * NULL. - * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. + * In Relative Mode, the platform-cursor's position usually contradicts the + * SDL-cursor's position as manually calculated from SDL_GetMouseState() and + * SDL_GetWindowPosition. * - * \since This function is available since SDL 3.0.0. + * This function can be useful if you need to track the mouse outside of a + * specific window and SDL_CaptureMouse() doesn't fit your needs. For example, + * it could be useful if you need to track the mouse while dragging a window, + * where coordinates relative to a window might not be in sync at all times. + * + * \param x a pointer to receive the platform-cursor's x-position from the + * desktop's top left corner, can be NULL if unused. + * \param y a pointer to receive the platform-cursor's y-position from the + * desktop's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CaptureMouse * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y); /** - * Retrieve the relative state of the mouse. + * Query SDL's cache for the synchronous mouse button state and accumulated + * mouse delta since last call. * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x a pointer filled with the last recorded x coordinate of the mouse. - * \param y a pointer filled with the last recorded y coordinate of the mouse. - * \returns a 32-bit button bitmask of the relative button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y deltas accumulated since the last call to this function + * (or since event initialization). + * + * This function is useful for reducing overhead by processing relative mouse + * inputs in one go per-frame instead of individually per-event, at the + * expense of losing the order between events within the frame (e.g. quickly + * pressing and releasing a button within the same frame). + * + * \param x a pointer to receive the x mouse delta accumulated since last + * call, can be NULL if unused. + * \param y a pointer to receive the y mouse delta accumulated since last + * call, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y); @@ -275,7 +347,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float * \param x the x coordinate within the window. * \param y the y coordinate within the window. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseGlobal */ @@ -295,14 +369,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * * \param x the x coordinate. * \param y the y coordinate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseInWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); /** * Set relative mouse mode for a window. @@ -312,31 +388,39 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * report continuous relative mouse motion even if the mouse is at the edge of * the window. * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * * This function will flush any pending mouse motion for this window. * * \param window the window to change. - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); /** * Query whether relative mouse mode is enabled for a window. * * \param window the window to query. - * \returns SDL_TRUE if relative mode is enabled for a window or SDL_FALSE - * otherwise. + * \returns true if relative mode is enabled for a window or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); /** * Capture the mouse and to track input outside an SDL window. @@ -374,15 +458,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window * * app, you can disable auto capture by setting the * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); /** * Create a cursor using the specified bitmap data and mask (in MSB format). @@ -419,7 +505,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); * \returns a new cursor with the specified parameters on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateSystemCursor @@ -450,7 +538,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data, * \returns the new cursor on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCursor * \sa SDL_CreateSystemCursor @@ -468,7 +558,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyCursor */ @@ -483,14 +575,16 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * this is desired for any reason. * * \param cursor a cursor to make active. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); /** * Get the active cursor. @@ -500,7 +594,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); * * \returns the active cursor or NULL if there is no mouse. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetCursor */ @@ -515,7 +611,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void); * \returns the default cursor on success or NULL on failuree; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); @@ -527,7 +625,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); * * \param cursor the cursor to free. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateCursor @@ -538,41 +638,47 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); /** * Show the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_HideCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); /** * Hide the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); /** * Return whether the cursor is currently being shown. * - * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the - * cursor is hidden. + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideCursor * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mutex.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mutex.h index 3a7ce56..c88ec15 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mutex.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_mutex.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,84 +25,245 @@ /** * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. */ #include +#include #include +#include -/******************************************************************************/ -/* Enable thread safety attributes only with clang. +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Enable thread safety attributes, only with clang. + * * The attributes can be safely erased when compiling with other compilers. * * To enable analysis, set these environment variables before running cmake: - * export CC=clang - * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` */ -#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ - defined(__clang__) && (!defined(SWIG)) +#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) + +#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG)) #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) #else #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ #endif +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SCOPED_CAPABILITY \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PT_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_BEFORE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_AFTER(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_GENERIC(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE_SHARED(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_EXCLUDES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_SHARED_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RETURN_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) @@ -130,7 +291,7 @@ extern "C" { * * https://en.wikipedia.org/wiki/Mutex * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Mutex SDL_Mutex; @@ -147,7 +308,7 @@ typedef struct SDL_Mutex SDL_Mutex; * \returns the initialized and unlocked mutex or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyMutex * \sa SDL_LockMutex @@ -173,7 +334,7 @@ extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); * * \param mutex the mutex to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockMutex * \sa SDL_UnlockMutex @@ -184,22 +345,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * Try to lock a mutex without blocking. * * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns SDL_FALSE immediately. + * this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. * - * This function returns SDL_TRUE if passed a NULL mutex. + * This function returns true if passed a NULL mutex. * * \param mutex the mutex to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the mutex would block. + * \returns true on success, false if the mutex would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_UnlockMutex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); /** * Unlock the mutex. @@ -213,7 +374,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ * * \param mutex the mutex to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_TryLockMutex @@ -231,7 +392,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m * * \param mutex the mutex to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateMutex */ @@ -261,7 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); * about how threads are scheduled and when they can be recursively locked. * These are documented in the other rwlock functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_RWLock SDL_RWLock; @@ -296,7 +457,7 @@ typedef struct SDL_RWLock SDL_RWLock; * \returns the initialized and unlocked read/write lock or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRWLock * \sa SDL_LockRWLockForReading @@ -336,7 +497,7 @@ extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading @@ -367,7 +528,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting @@ -379,7 +540,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Try to lock a read/write lock _for reading_ without blocking. * * This works just like SDL_LockRWLockForReading(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need access to a resource but don't want to * wait for it, and will return to it to try again later. @@ -387,24 +548,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Trying to lock for read-only access can succeed if other threads are * holding read-only locks, as this won't prevent access. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); /** * Try to lock a read/write lock _for writing_ without blocking. * * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. @@ -417,18 +578,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwl * read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock before requesting a write lock. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); /** * Unlock the read/write lock. @@ -446,7 +607,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwl * * \param rwlock the rwlock to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_LockRWLockForWriting @@ -466,7 +627,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS * * \param rwlock the rwlock to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRWLock */ @@ -492,7 +653,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); * * https://en.wikipedia.org/wiki/Semaphore_(programming) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Semaphore SDL_Semaphore; @@ -509,7 +670,7 @@ typedef struct SDL_Semaphore SDL_Semaphore; * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySemaphore * \sa SDL_SignalSemaphore @@ -528,7 +689,7 @@ extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_v * * \param sem the semaphore to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSemaphore */ @@ -546,7 +707,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * * \param sem the semaphore wait on. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore @@ -560,18 +721,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * This function checks to see if the semaphore pointed to by `sem` has a * positive value and atomically decrements the semaphore value if it does. If * the semaphore doesn't have a positive value, the function immediately - * returns SDL_FALSE. + * returns false. * * \param sem the semaphore to wait on. - * \returns SDL_TRUE if the wait succeeds, SDL_FALSE if the wait would block. + * \returns true if the wait succeeds, false if the wait would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. @@ -583,22 +744,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to wait on. * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the wait succeeds or SDL_FALSE if the wait times out. + * \returns true if the wait succeeds or false if the wait times out. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); /** * Atomically increment a semaphore's value and wake waiting threads. * * \param sem the semaphore to increment. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore @@ -612,7 +773,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to query. * \returns the current value of the semaphore. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); @@ -635,7 +796,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); * * https://en.wikipedia.org/wiki/Condition_variable * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Condition SDL_Condition; @@ -645,7 +806,7 @@ typedef struct SDL_Condition SDL_Condition; * \returns a new condition variable or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -660,7 +821,7 @@ extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); * * \param cond the condition variable to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCondition */ @@ -673,7 +834,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_WaitCondition @@ -688,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalCondition * \sa SDL_WaitCondition @@ -716,7 +877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -741,22 +902,167 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mute * \param mutex the mutex used to coordinate thread access. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the condition variable is signaled, SDL_FALSE if the - * condition is not signaled in the allotted time. + * \returns true if the condition variable is signaled, false if the condition + * is not signaled in the allotted time. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition * \sa SDL_WaitCondition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, SDL_Mutex *mutex, Sint32 timeoutMS); /* @} *//* Condition variable functions */ +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * DoQuitTasks(); + * SDL_SetInitialized(&init, false); + * } + * ``` + * + * Note that this doesn't protect any resources created during initialization, + * or guarantee that nobody is using those resources during cleanup. You + * should use other mechanisms to protect those, if that's a concern for your + * code. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_oldnames.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_oldnames.h index 02c881c..c93607e 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_oldnames.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_oldnames.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -38,11 +38,14 @@ #ifdef SDL_ENABLE_OLD_NAMES /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer #define SDL_AtomicLock SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_UnlockSpinlock #define SDL_atomic_t SDL_AtomicInt @@ -74,6 +77,7 @@ #define SDL_NewAudioStream SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -166,14 +170,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -193,7 +196,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -304,6 +307,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -419,9 +424,15 @@ #define SDL_LogSetAllPriority SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK #define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT @@ -558,6 +569,7 @@ #define SDL_WriteLE64 SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -580,7 +592,12 @@ #define SDL_SensorUpdate SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE false #define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtok_r /* ##SDL_surface.h */ @@ -623,14 +640,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iPhoneSetEventPump SDL_SetiOSEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_CleanupTLS #define SDL_TLSGet SDL_GetTLS #define SDL_TLSSet SDL_SetTLS @@ -645,6 +661,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint @@ -661,11 +681,14 @@ #elif !defined(SDL_DISABLE_OLD_NAMES) /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer #define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock #define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt @@ -697,6 +720,7 @@ #define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -789,14 +813,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_WINDOWEVENT_RESTORED_renamed_SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_WINDOWEVENT_SHOWN_renamed_SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_WINDOWEVENT_TAKE_FOCUS_renamed_SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_eventaction_renamed_SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_CONTROLLER_AXIS_RIGHTX_renamed_SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_CONTROLLER_AXIS_RIGHTY_renamed_SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_CONTROLLER_AXIS_TRIGGERLEFT_renamed_SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -816,7 +839,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_CONTROLLER_BUTTON_INVALID_renamed_SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_CONTROLLER_BUTTON_LEFTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_CONTROLLER_BUTTON_LEFTSTICK_renamed_SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_CONTROLLER_BUTTON_MISC1_renamed_SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_CONTROLLER_BUTTON_PADDLE1_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_CONTROLLER_BUTTON_PADDLE2_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -928,6 +951,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE_renamed_SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_LINUX_DIGITAL_HATS_renamed_SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_LINUX_HAT_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_LINUX_JOYSTICK_CLASSIC_renamed_SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -1043,9 +1068,15 @@ #define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK #define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT @@ -1182,6 +1213,7 @@ #define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -1204,7 +1236,12 @@ #define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false #define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r /* ##SDL_surface.h */ @@ -1247,14 +1284,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_WinRTGetDeviceFamily_renamed_SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPathUTF8_renamed_SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback #define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS #define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS #define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS @@ -1269,6 +1305,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DeleteContext_renamed_SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLattr_renamed_SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLcontextFlag_renamed_SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLcontextReleaseFlag_renamed_SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLprofile_renamed_SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestDisplayMode_renamed_SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetDisplayOrientation_renamed_SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengl.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengl.h index 6bdcbe0..d1b8b02 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengl.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -783,6 +783,7 @@ typedef double GLclampd; /* double precision float in [0,1] */ * Miscellaneous */ +#ifndef SDL_OPENGL_1_NO_PROTOTYPES GLAPI void GLAPIENTRY glClearIndex( GLfloat c ); GLAPI void GLAPIENTRY glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); @@ -1480,6 +1481,706 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); + +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); + +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); + +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); + +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); + +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); + +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); + +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); + +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); + +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); + +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); + +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); + +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); + +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); + +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); + +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); + +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); + +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); + + +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + + +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); + +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); + +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); + + +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ + + +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); + +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); + +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); + +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); + +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); + +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); + + +/* + * Depth Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARDEPTHPROC) ( GLclampd depth ); + +typedef void (APIENTRYP PFNGLDEPTHFUNCPROC) ( GLenum func ); + +typedef void (APIENTRYP PFNGLDEPTHMASKPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLDEPTHRANGEPROC) ( GLclampd near_val, GLclampd far_val ); + + +/* + * Accumulation Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARACCUMPROC) ( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha ); + +typedef void (APIENTRYP PFNGLACCUMPROC) ( GLenum op, GLfloat value ); + + +/* + * Transformation + */ + +typedef void (APIENTRYP PFNGLMATRIXMODEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLORTHOPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLFRUSTUMPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLVIEWPORTPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height ); + +typedef void (APIENTRYP PFNGLPUSHMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLPOPMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADIDENTITYPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLLOADMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLMULTMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLMULTMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLROTATEDPROC) ( GLdouble angle, + GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLROTATEFPROC) ( GLfloat angle, + GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLSCALEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLSCALEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLTRANSLATEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLTRANSLATEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + + +/* + * Display Lists + */ + +typedef GLboolean (APIENTRYP PFNGLISLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLDELETELISTSPROC) ( GLuint list, GLsizei range ); + +typedef GLuint (APIENTRYP PFNGLGENLISTSPROC) ( GLsizei range ); + +typedef void (APIENTRYP PFNGLNEWLISTPROC) ( GLuint list, GLenum mode ); + +typedef void (APIENTRYP PFNGLENDLISTPROC) ( void ); + +typedef void (APIENTRYP PFNGLCALLLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLCALLLISTSPROC) ( GLsizei n, GLenum type, + const GLvoid *lists ); + +typedef void (APIENTRYP PFNGLLISTBASEPROC) ( GLuint base ); + + +/* + * Drawing Functions + */ + +typedef void (APIENTRYP PFNGLBEGINPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENDPROC) ( void ); + + +typedef void (APIENTRYP PFNGLVERTEX2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLVERTEX2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLVERTEX2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLVERTEX2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLVERTEX3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLVERTEX3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLVERTEX3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLVERTEX3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLVERTEX4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLVERTEX4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLVERTEX4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLVERTEX4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLVERTEX2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLNORMAL3BPROC) ( GLbyte nx, GLbyte ny, GLbyte nz ); +typedef void (APIENTRYP PFNGLNORMAL3DPROC) ( GLdouble nx, GLdouble ny, GLdouble nz ); +typedef void (APIENTRYP PFNGLNORMAL3FPROC) ( GLfloat nx, GLfloat ny, GLfloat nz ); +typedef void (APIENTRYP PFNGLNORMAL3IPROC) ( GLint nx, GLint ny, GLint nz ); +typedef void (APIENTRYP PFNGLNORMAL3SPROC) ( GLshort nx, GLshort ny, GLshort nz ); + +typedef void (APIENTRYP PFNGLNORMAL3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLNORMAL3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLNORMAL3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLNORMAL3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLNORMAL3SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLINDEXDPROC) ( GLdouble c ); +typedef void (APIENTRYP PFNGLINDEXFPROC) ( GLfloat c ); +typedef void (APIENTRYP PFNGLINDEXIPROC) ( GLint c ); +typedef void (APIENTRYP PFNGLINDEXSPROC) ( GLshort c ); +typedef void (APIENTRYP PFNGLINDEXUBPROC) ( GLubyte c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLINDEXDVPROC) ( const GLdouble *c ); +typedef void (APIENTRYP PFNGLINDEXFVPROC) ( const GLfloat *c ); +typedef void (APIENTRYP PFNGLINDEXIVPROC) ( const GLint *c ); +typedef void (APIENTRYP PFNGLINDEXSVPROC) ( const GLshort *c ); +typedef void (APIENTRYP PFNGLINDEXUBVPROC) ( const GLubyte *c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLCOLOR3BPROC) ( GLbyte red, GLbyte green, GLbyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3DPROC) ( GLdouble red, GLdouble green, GLdouble blue ); +typedef void (APIENTRYP PFNGLCOLOR3FPROC) ( GLfloat red, GLfloat green, GLfloat blue ); +typedef void (APIENTRYP PFNGLCOLOR3IPROC) ( GLint red, GLint green, GLint blue ); +typedef void (APIENTRYP PFNGLCOLOR3SPROC) ( GLshort red, GLshort green, GLshort blue ); +typedef void (APIENTRYP PFNGLCOLOR3UBPROC) ( GLubyte red, GLubyte green, GLubyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3UIPROC) ( GLuint red, GLuint green, GLuint blue ); +typedef void (APIENTRYP PFNGLCOLOR3USPROC) ( GLushort red, GLushort green, GLushort blue ); + +typedef void (APIENTRYP PFNGLCOLOR4BPROC) ( GLbyte red, GLbyte green, + GLbyte blue, GLbyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4DPROC) ( GLdouble red, GLdouble green, + GLdouble blue, GLdouble alpha ); +typedef void (APIENTRYP PFNGLCOLOR4FPROC) ( GLfloat red, GLfloat green, + GLfloat blue, GLfloat alpha ); +typedef void (APIENTRYP PFNGLCOLOR4IPROC) ( GLint red, GLint green, + GLint blue, GLint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4SPROC) ( GLshort red, GLshort green, + GLshort blue, GLshort alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UBPROC) ( GLubyte red, GLubyte green, + GLubyte blue, GLubyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UIPROC) ( GLuint red, GLuint green, + GLuint blue, GLuint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4USPROC) ( GLushort red, GLushort green, + GLushort blue, GLushort alpha ); + + +typedef void (APIENTRYP PFNGLCOLOR3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR3SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR3UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR3USVPROC) ( const GLushort *v ); + +typedef void (APIENTRYP PFNGLCOLOR4BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR4SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR4UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR4USVPROC) ( const GLushort *v ); + + +typedef void (APIENTRYP PFNGLTEXCOORD1DPROC) ( GLdouble s ); +typedef void (APIENTRYP PFNGLTEXCOORD1FPROC) ( GLfloat s ); +typedef void (APIENTRYP PFNGLTEXCOORD1IPROC) ( GLint s ); +typedef void (APIENTRYP PFNGLTEXCOORD1SPROC) ( GLshort s ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DPROC) ( GLdouble s, GLdouble t ); +typedef void (APIENTRYP PFNGLTEXCOORD2FPROC) ( GLfloat s, GLfloat t ); +typedef void (APIENTRYP PFNGLTEXCOORD2IPROC) ( GLint s, GLint t ); +typedef void (APIENTRYP PFNGLTEXCOORD2SPROC) ( GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DPROC) ( GLdouble s, GLdouble t, GLdouble r ); +typedef void (APIENTRYP PFNGLTEXCOORD3FPROC) ( GLfloat s, GLfloat t, GLfloat r ); +typedef void (APIENTRYP PFNGLTEXCOORD3IPROC) ( GLint s, GLint t, GLint r ); +typedef void (APIENTRYP PFNGLTEXCOORD3SPROC) ( GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DPROC) ( GLdouble s, GLdouble t, GLdouble r, GLdouble q ); +typedef void (APIENTRYP PFNGLTEXCOORD4FPROC) ( GLfloat s, GLfloat t, GLfloat r, GLfloat q ); +typedef void (APIENTRYP PFNGLTEXCOORD4IPROC) ( GLint s, GLint t, GLint r, GLint q ); +typedef void (APIENTRYP PFNGLTEXCOORD4SPROC) ( GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLTEXCOORD1DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRASTERPOS2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLRASTERPOS2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLRASTERPOS2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLRASTERPOS2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLRASTERPOS3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLRASTERPOS3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLRASTERPOS3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLRASTERPOS4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLRASTERPOS4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLRASTERPOS4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLRASTERPOS2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRECTDPROC) ( GLdouble x1, GLdouble y1, GLdouble x2, GLdouble y2 ); +typedef void (APIENTRYP PFNGLRECTFPROC) ( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ); +typedef void (APIENTRYP PFNGLRECTIPROC) ( GLint x1, GLint y1, GLint x2, GLint y2 ); +typedef void (APIENTRYP PFNGLRECTSPROC) ( GLshort x1, GLshort y1, GLshort x2, GLshort y2 ); + + +typedef void (APIENTRYP PFNGLRECTDVPROC) ( const GLdouble *v1, const GLdouble *v2 ); +typedef void (APIENTRYP PFNGLRECTFVPROC) ( const GLfloat *v1, const GLfloat *v2 ); +typedef void (APIENTRYP PFNGLRECTIVPROC) ( const GLint *v1, const GLint *v2 ); +typedef void (APIENTRYP PFNGLRECTSVPROC) ( const GLshort *v1, const GLshort *v2 ); + + +/* + * Vertex Arrays (1.1) + */ + +typedef void (APIENTRYP PFNGLVERTEXPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLNORMALPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLCOLORPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLINDEXPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLTEXCOORDPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPOINTERPROC) ( GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLGETPOINTERVPROC) ( GLenum pname, GLvoid **params ); + +typedef void (APIENTRYP PFNGLARRAYELEMENTPROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLDRAWARRAYSPROC) ( GLenum mode, GLint first, GLsizei count ); + +typedef void (APIENTRYP PFNGLDRAWELEMENTSPROC) ( GLenum mode, GLsizei count, + GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLINTERLEAVEDARRAYSPROC) ( GLenum format, GLsizei stride, + const GLvoid *pointer ); + +/* + * Lighting + */ + +typedef void (APIENTRYP PFNGLSHADEMODELPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLLIGHTFPROC) ( GLenum light, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTIPROC) ( GLenum light, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTFVPROC) ( GLenum light, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTIVPROC) ( GLenum light, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETLIGHTFVPROC) ( GLenum light, GLenum pname, + GLfloat *params ); +typedef void (APIENTRYP PFNGLGETLIGHTIVPROC) ( GLenum light, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLLIGHTMODELFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTMODELIPROC) ( GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTMODELFVPROC) ( GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTMODELIVPROC) ( GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLMATERIALFPROC) ( GLenum face, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLMATERIALIPROC) ( GLenum face, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLMATERIALFVPROC) ( GLenum face, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLMATERIALIVPROC) ( GLenum face, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETMATERIALFVPROC) ( GLenum face, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETMATERIALIVPROC) ( GLenum face, GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLCOLORMATERIALPROC) ( GLenum face, GLenum mode ); + + +/* + * Raster functions + */ + +typedef void (APIENTRYP PFNGLPIXELZOOMPROC) ( GLfloat xfactor, GLfloat yfactor ); + +typedef void (APIENTRYP PFNGLPIXELSTOREFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELSTOREIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELTRANSFERFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELTRANSFERIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELMAPFVPROC) ( GLenum map, GLsizei mapsize, + const GLfloat *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUIVPROC) ( GLenum map, GLsizei mapsize, + const GLuint *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUSVPROC) ( GLenum map, GLsizei mapsize, + const GLushort *values ); + +typedef void (APIENTRYP PFNGLGETPIXELMAPFVPROC) ( GLenum map, GLfloat *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUIVPROC) ( GLenum map, GLuint *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUSVPROC) ( GLenum map, GLushort *values ); + +typedef void (APIENTRYP PFNGLBITMAPPROC) ( GLsizei width, GLsizei height, + GLfloat xorig, GLfloat yorig, + GLfloat xmove, GLfloat ymove, + const GLubyte *bitmap ); + +typedef void (APIENTRYP PFNGLREADPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLDRAWPIXELSPROC) ( GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLCOPYPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum type ); + +/* + * Stenciling + */ + +typedef void (APIENTRYP PFNGLSTENCILFUNCPROC) ( GLenum func, GLint ref, GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILOPPROC) ( GLenum fail, GLenum zfail, GLenum zpass ); + +typedef void (APIENTRYP PFNGLCLEARSTENCILPROC) ( GLint s ); + + + +/* + * Texture mapping + */ + +typedef void (APIENTRYP PFNGLTEXGENDPROC) ( GLenum coord, GLenum pname, GLdouble param ); +typedef void (APIENTRYP PFNGLTEXGENFPROC) ( GLenum coord, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXGENIPROC) ( GLenum coord, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXGENDVPROC) ( GLenum coord, GLenum pname, const GLdouble *params ); +typedef void (APIENTRYP PFNGLTEXGENFVPROC) ( GLenum coord, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXGENIVPROC) ( GLenum coord, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXGENDVPROC) ( GLenum coord, GLenum pname, GLdouble *params ); +typedef void (APIENTRYP PFNGLGETTEXGENFVPROC) ( GLenum coord, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXGENIVPROC) ( GLenum coord, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXENVFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXENVIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXENVFVPROC) ( GLenum target, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXENVIVPROC) ( GLenum target, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXENVFVPROC) ( GLenum target, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXENVIVPROC) ( GLenum target, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXPARAMETERFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXPARAMETERFVPROC) ( GLenum target, + GLenum pname, GLfloat *params); +typedef void (APIENTRYP PFNGLGETTEXPARAMETERIVPROC) ( GLenum target, + GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERFVPROC) ( GLenum target, GLint level, + GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERIVPROC) ( GLenum target, GLint level, + GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLint border, GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLGETTEXIMAGEPROC) ( GLenum target, GLint level, + GLenum format, GLenum type, + GLvoid *pixels ); + + +/* 1.1 functions */ + +typedef void (APIENTRYP PFNGLGENTEXTURESPROC) ( GLsizei n, GLuint *textures ); + +typedef void (APIENTRYP PFNGLDELETETEXTURESPROC) ( GLsizei n, const GLuint *textures); + +typedef void (APIENTRYP PFNGLBINDTEXTUREPROC) ( GLenum target, GLuint texture ); + +typedef void (APIENTRYP PFNGLPRIORITIZETEXTURESPROC) ( GLsizei n, + const GLuint *textures, + const GLclampf *priorities ); + +typedef GLboolean (APIENTRYP PFNGLARETEXTURESRESIDENTPROC) ( GLsizei n, + const GLuint *textures, + GLboolean *residences ); + +typedef GLboolean (APIENTRYP PFNGLISTEXTUREPROC) ( GLuint texture ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, + GLsizei width, GLenum format, + GLenum type, const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLsizei height, + GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint x, GLint y, + GLsizei width ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint x, GLint y, + GLsizei width, GLsizei height ); + + +/* + * Evaluators + */ + +typedef void (APIENTRYP PFNGLMAP1DPROC) ( GLenum target, GLdouble u1, GLdouble u2, + GLint stride, + GLint order, const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP1FPROC) ( GLenum target, GLfloat u1, GLfloat u2, + GLint stride, + GLint order, const GLfloat *points ); + +typedef void (APIENTRYP PFNGLMAP2DPROC) ( GLenum target, + GLdouble u1, GLdouble u2, GLint ustride, GLint uorder, + GLdouble v1, GLdouble v2, GLint vstride, GLint vorder, + const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP2FPROC) ( GLenum target, + GLfloat u1, GLfloat u2, GLint ustride, GLint uorder, + GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, + const GLfloat *points ); + +typedef void (APIENTRYP PFNGLGETMAPDVPROC) ( GLenum target, GLenum query, GLdouble *v ); +typedef void (APIENTRYP PFNGLGETMAPFVPROC) ( GLenum target, GLenum query, GLfloat *v ); +typedef void (APIENTRYP PFNGLGETMAPIVPROC) ( GLenum target, GLenum query, GLint *v ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DPROC) ( GLdouble u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FPROC) ( GLfloat u ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DPROC) ( GLdouble u, GLdouble v ); +typedef void (APIENTRYP PFNGLEVALCOORD2FPROC) ( GLfloat u, GLfloat v ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD2FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLMAPGRID1DPROC) ( GLint un, GLdouble u1, GLdouble u2 ); +typedef void (APIENTRYP PFNGLMAPGRID1FPROC) ( GLint un, GLfloat u1, GLfloat u2 ); + +typedef void (APIENTRYP PFNGLMAPGRID2DPROC) ( GLint un, GLdouble u1, GLdouble u2, + GLint vn, GLdouble v1, GLdouble v2 ); +typedef void (APIENTRYP PFNGLMAPGRID2FPROC) ( GLint un, GLfloat u1, GLfloat u2, + GLint vn, GLfloat v1, GLfloat v2 ); + +typedef void (APIENTRYP PFNGLEVALPOINT1PROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLEVALPOINT2PROC) ( GLint i, GLint j ); + +typedef void (APIENTRYP PFNGLEVALMESH1PROC) ( GLenum mode, GLint i1, GLint i2 ); + +typedef void (APIENTRYP PFNGLEVALMESH2PROC) ( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + + +/* + * Fog + */ + +typedef void (APIENTRYP PFNGLFOGFPROC) ( GLenum pname, GLfloat param ); + +typedef void (APIENTRYP PFNGLFOGIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLFOGFVPROC) ( GLenum pname, const GLfloat *params ); + +typedef void (APIENTRYP PFNGLFOGIVPROC) ( GLenum pname, const GLint *params ); + + +/* + * Selection and Feedback + */ + +typedef void (APIENTRYP PFNGLFEEDBACKBUFFERPROC) ( GLsizei size, GLenum type, GLfloat *buffer ); + +typedef void (APIENTRYP PFNGLPASSTHROUGHPROC) ( GLfloat token ); + +typedef void (APIENTRYP PFNGLSELECTBUFFERPROC) ( GLsizei size, GLuint *buffer ); + +typedef void (APIENTRYP PFNGLINITNAMESPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPUSHNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPOPNAMEPROC) ( void ); +#endif /* @@ -1528,6 +2229,8 @@ GLAPI void GLAPIENTRY glPopName( void ); #define GL_MAX_3D_TEXTURE_SIZE 0x8073 #define GL_TEXTURE_BINDING_3D 0x806A +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); @@ -1551,6 +2254,34 @@ GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, GLint y, GLsizei width, GLsizei height ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) ( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif + typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); @@ -1638,6 +2369,8 @@ typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, #define GL_BLEND_COLOR 0x8005 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, GLsizei width, GLenum format, GLenum type, const GLvoid *table ); @@ -1746,6 +2479,119 @@ GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +typedef void (APIENTRYP PFNGLCOLORSUBTABLEPROC) ( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERIVPROC) (GLenum target, GLenum pname, + const GLint *params); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERFVPROC) (GLenum target, GLenum pname, + const GLfloat *params); + +typedef void (APIENTRYP PFNGLCOPYCOLORSUBTABLEPROC) ( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLBLENDEQUATIONPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLBLENDCOLORPROC) ( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLHISTOGRAMPROC) ( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETHISTOGRAMPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLMINMAXPROC) ( GLenum target, GLenum internalformat, + GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETMINMAXPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETMINMAXPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFPROC) ( GLenum target, GLenum pname, + GLfloat params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIPROC) ( GLenum target, GLenum pname, + GLint params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLSEPARABLEFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +typedef void (APIENTRYP PFNGLGETSEPARABLEFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif + @@ -1858,6 +2704,8 @@ GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, /* texture_border_clamp */ #define GL_CLAMP_TO_BORDER 0x812D +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTexture( GLenum texture ); GLAPI void GLAPIENTRY glClientActiveTexture( GLenum texture ); @@ -1951,6 +2799,104 @@ GLAPI void GLAPIENTRY glMultTransposeMatrixf( const GLfloat m[16] ); GLAPI void GLAPIENTRY glSampleCoverage( GLclampf value, GLboolean invert ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE1DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE2DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE3DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) ( GLenum target, GLint lod, GLvoid *img ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DPROC) ( GLenum target, GLdouble s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FPROC) ( GLenum target, GLfloat s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IPROC) ( GLenum target, GLint s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SPROC) ( GLenum target, GLshort s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DPROC) ( GLenum target, GLdouble s, GLdouble t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FPROC) ( GLenum target, GLfloat s, GLfloat t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IPROC) ( GLenum target, GLint s, GLint t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SPROC) ( GLenum target, GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IPROC) ( GLenum target, GLint s, GLint t, GLint r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IPROC) ( GLenum target, GLint s, GLint t, GLint r, GLint q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVPROC) ( GLenum target, const GLshort *v ); + + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) ( GLclampf value, GLboolean invert ); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) (GLenum texture); typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) (GLclampf value, GLboolean invert); @@ -2006,6 +2952,8 @@ typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) (GLenum target, GLint le #define GL_CLIENT_ACTIVE_TEXTURE_ARB 0x84E1 #define GL_MAX_TEXTURE_UNITS_ARB 0x84E2 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glClientActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glMultiTexCoord1dARB(GLenum target, GLdouble s); @@ -2041,6 +2989,46 @@ GLAPI void GLAPIENTRY glMultiTexCoord4ivARB(GLenum target, const GLint *v); GLAPI void GLAPIENTRY glMultiTexCoord4sARB(GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); GLAPI void GLAPIENTRY glMultiTexCoord4svARB(GLenum target, const GLshort *v); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FARBPROC) (GLenum target, GLfloat s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IARBPROC) (GLenum target, GLint s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SARBPROC) (GLenum target, GLshort s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DARBPROC) (GLenum target, GLdouble s, GLdouble t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FARBPROC) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IARBPROC) (GLenum target, GLint s, GLint t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SARBPROC) (GLenum target, GLshort s, GLshort t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IARBPROC) (GLenum target, GLint s, GLint t, GLint r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IARBPROC) (GLenum target, GLint s, GLint t, GLint r, GLint q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLshort *v); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles.h index bde4d74..4fb9a4b 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles2.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles2.h index ba19601..365898a 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles2.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_opengles2.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pen.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pen.h index cda4f0f..5182eeb 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pen.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pen.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -39,7 +39,9 @@ #ifndef SDL_pen_h_ #define SDL_pen_h_ -#include +#include +#include +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -55,24 +57,39 @@ extern "C" { * consistent as long as SDL can recognize a tool to be the same pen; but if a * pen physically leaves the area and returns, it might get a new ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenID; +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + /** * Pen input flags, as reported by various pen events' `pen_state` field. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenInputFlags; -#define SDL_PEN_INPUT_DOWN (1u << 0) /**< & to see if pen is pressed down */ -#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< & to see if button 1 is pressed */ -#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< & to see if button 2 is pressed */ -#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< & to see if button 3 is pressed */ -#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< & to see if button 4 is pressed */ -#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< & to see if button 5 is pressed */ -#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< & to see if eraser tip is used */ + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ /** * Pen axis indices. @@ -87,20 +104,18 @@ typedef Uint32 SDL_PenInputFlags; * * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PenAxis { SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ - SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). - The physical max/min tilt may be smaller than -90.0 / 90.0, check SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). - The physical max/min tilt may be smaller than -90.0 / 90.0 check SDL_PenCapabilityInfo */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ - SDL_PEN_NUM_AXES /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ } SDL_PenAxis; /* Ends C function definitions when using C++ */ @@ -110,4 +125,3 @@ typedef enum SDL_PenAxis #endif /* SDL_pen_h_ */ -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pixels.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pixels.h index 3825dd5..b6f38ac 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pixels.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_pixels.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,59 @@ /** * # CategoryPixels * - * Pixel management. + * SDL offers facilities for pixel management. + * + * Largely these facilities deal with pixel _format_: what does this set of + * bits represent? + * + * If you mostly want to think of a pixel as some combination of red, green, + * blue, and maybe alpha intensities, this is all pretty straightforward, and + * in many cases, is enough information to build a perfectly fine game. + * + * However, the actual definition of a pixel is more complex than that: + * + * Pixels are a representation of a color in a particular color space. + * + * The first characteristic of a color space is the color type. SDL + * understands two different color types, RGB and YCbCr, or in SDL also + * referred to as YUV. + * + * RGB colors consist of red, green, and blue channels of color that are added + * together to represent the colors we see on the screen. + * + * https://en.wikipedia.org/wiki/RGB_color_model + * + * YCbCr colors represent colors as a Y luma brightness component and red and + * blue chroma color offsets. This color representation takes advantage of the + * fact that the human eye is more sensitive to brightness than the color in + * an image. The Cb and Cr components are often compressed and have lower + * resolution than the luma component. + * + * https://en.wikipedia.org/wiki/YCbCr + * + * When the color information in YCbCr is compressed, the Y pixels are left at + * full resolution and each Cr and Cb pixel represents an average of the color + * information in a block of Y pixels. The chroma location determines where in + * that block of pixels the color information is coming from. + * + * The color range defines how much of the pixel to use when converting a + * pixel into a color on the display. When the full color range is used, the + * entire numeric range of the pixel bits is significant. When narrow color + * range is used, for historical reasons, the pixel uses only a portion of the + * numeric range to represent colors. + * + * The color primaries and white point are a definition of the colors in the + * color space relative to the standard XYZ color space. + * + * https://en.wikipedia.org/wiki/CIE_1931_color_space + * + * The transfer characteristic, or opto-electrical transfer function (OETF), + * is the way a color is converted from mathematically linear space into a + * non-linear output signals. + * + * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics + * + * The matrix coefficients are used to convert between YCbCr and RGB colors. */ #ifndef SDL_pixels_h_ @@ -41,22 +93,44 @@ extern "C" { /** * A fully opaque 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_TRANSPARENT */ #define SDL_ALPHA_OPAQUE 255 +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + /** * A fully transparent 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_OPAQUE */ #define SDL_ALPHA_TRANSPARENT 0 -/** Pixel type. */ +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, @@ -75,7 +149,11 @@ typedef enum SDL_PixelType SDL_PIXELTYPE_INDEX2 } SDL_PixelType; -/** Bitmap pixel order, high bit -> low bit. */ +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, @@ -83,7 +161,11 @@ typedef enum SDL_BitmapOrder SDL_BITMAPORDER_1234 } SDL_BitmapOrder; -/** Packed component order, high bit -> low bit. */ +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, @@ -97,7 +179,11 @@ typedef enum SDL_PackedOrder SDL_PACKEDORDER_BGRA } SDL_PackedOrder; -/** Array component order, low byte -> high byte. */ +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, @@ -109,7 +195,11 @@ typedef enum SDL_ArrayOrder SDL_ARRAYORDER_ABGR } SDL_ArrayOrder; -/** Packed component layout. */ +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, @@ -123,25 +213,172 @@ typedef enum SDL_PackedLayout SDL_PACKEDLAYOUT_1010102 } SDL_PackedLayout; +/** + * A macro for defining custom FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_YV12 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') + * ``` + * + * \param A the first character of the FourCC code. + * \param B the second character of the FourCC code. + * \param C the third character of the FourCC code. + * \param D the fourth character of the FourCC code. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) +/** + * A macro for defining custom non-FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) + * ``` + * + * \param type the type of the new format, probably a SDL_PixelType value. + * \param order the order of the new format, probably a SDL_BitmapOrder, + * SDL_PackedOrder, or SDL_ArrayOrder value. + * \param layout the layout of the new format, probably an SDL_PackedLayout + * value or zero. + * \param bits the number of bits per pixel of the new format. + * \param bytes the number of bytes per pixel of the new format. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ ((bits) << 8) | ((bytes) << 0)) -#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) -#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) -#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) -#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) -#define SDL_BITSPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU) || \ - ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF)) +/** + * A macro to retrieve the flags of an SDL_PixelFormat. + * + * This macro is generally not needed directly by an app, which should use + * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. + * + * \param format an SDL_PixelFormat to check. + * \returns the flags of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) +/** + * A macro to retrieve the type of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PixelType enumeration. + * + * \param format an SDL_PixelFormat to check. + * \returns the type of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) + +/** + * A macro to retrieve the order of an SDL_PixelFormat. + * + * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or + * SDL_ArrayOrder enumerations, depending on the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the order of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) + +/** + * A macro to retrieve the layout of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PackedLayout enumeration, or zero if a + * layout doesn't make sense for the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the layout of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) + +/** + * A macro to determine an SDL_PixelFormat's bits per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats will report zero here, as it rarely makes sense to measure + * them per-pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bits-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTESPERPIXEL + */ +#define SDL_BITSPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) + +/** + * A macro to determine an SDL_PixelFormat's bytes per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats do their best here, but many of them don't have a meaningful + * measurement of bytes per pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bytes-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BITSPERPIXEL + */ +#define SDL_BYTESPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? \ + ((((format) == SDL_PIXELFORMAT_YUY2) || \ + ((format) == SDL_PIXELFORMAT_UYVY) || \ + ((format) == SDL_PIXELFORMAT_YVYU) || \ + ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) + + +/** + * A macro to determine if an SDL_PixelFormat is an indexed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is indexed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -149,12 +386,38 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) +/** + * A macro to determine if an SDL_PixelFormat is a packed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is packed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_PACKED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) +/** + * A macro to determine if an SDL_PixelFormat is an array format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is an array, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -163,25 +426,84 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -#define SDL_ISPIXELFORMAT_ALPHA(format) \ - ((SDL_ISPIXELFORMAT_PACKED(format) && \ - ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))) - +/** + * A macro to determine if an SDL_PixelFormat is a 10-bit format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_10BIT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) +/** + * A macro to determine if an SDL_PixelFormat is a floating point format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ -#define SDL_ISPIXELFORMAT_FOURCC(format) \ +/** + * A macro to determine if an SDL_PixelFormat has an alpha channel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_ALPHA(format) \ + ((SDL_ISPIXELFORMAT_PACKED(format) && \ + ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ + (SDL_ISPIXELFORMAT_ARRAY(format) && \ + ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) + + +/** + * A macro to determine if an SDL_PixelFormat is a "FourCC" format. + * + * This covers custom and other unusual formats. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this enum, update SDL_GetPixelFormatName() */ @@ -221,7 +543,7 @@ typedef enum SDL_PackedLayout * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for * RGBA8888 on big-endian CPUs. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PixelFormat { @@ -351,59 +673,35 @@ typedef enum SDL_PixelFormat /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ - SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif } SDL_PixelFormat; -/* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 -#else -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888 -#endif - -/** - * Pixels are a representation of a color in a particular color space. - * - * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV. - * - * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen. - * https://en.wikipedia.org/wiki/RGB_color_model - * - * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component. - * https://en.wikipedia.org/wiki/YCbCr - * - * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from. - * - * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors. - * - * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space. - * https://en.wikipedia.org/wiki/CIE_1931_color_space - * - * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals. - * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics - * - * The matrix coefficients are used to convert between YCbCr and RGB colors. - */ - /** * Colorspace color type. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorType { @@ -416,7 +714,7 @@ typedef enum SDL_ColorType * Colorspace color range, as described by * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorRange { @@ -429,7 +727,7 @@ typedef enum SDL_ColorRange * Colorspace color primaries, as described by * https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorPrimaries { @@ -454,7 +752,7 @@ typedef enum SDL_ColorPrimaries * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TransferCharacteristics { @@ -484,7 +782,7 @@ typedef enum SDL_TransferCharacteristics * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MatrixCoefficients { @@ -508,7 +806,7 @@ typedef enum SDL_MatrixCoefficients /** * Colorspace chroma sample location. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ChromaLocation { @@ -520,22 +818,177 @@ typedef enum SDL_ChromaLocation /* Colorspace definition */ + +/** + * A macro for defining custom SDL_Colorspace formats. + * + * For example, defining SDL_COLORSPACE_SRGB looks like this: + * + * ```c + * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + * SDL_COLOR_RANGE_FULL, + * SDL_COLOR_PRIMARIES_BT709, + * SDL_TRANSFER_CHARACTERISTICS_SRGB, + * SDL_MATRIX_COEFFICIENTS_IDENTITY, + * SDL_CHROMA_LOCATION_NONE) + * ``` + * + * \param type the type of the new format, probably an SDL_ColorType value. + * \param range the range of the new format, probably a SDL_ColorRange value. + * \param primaries the primaries of the new format, probably an + * SDL_ColorPrimaries value. + * \param transfer the transfer characteristics of the new format, probably an + * SDL_TransferCharacteristics value. + * \param matrix the matrix coefficients of the new format, probably an + * SDL_MatrixCoefficients value. + * \param chroma the chroma sample location of the new format, probably an + * SDL_ChromaLocation value. + * \returns a format value in the style of SDL_Colorspace. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) -#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F) -#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F) -#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F) -#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) -#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) -#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F) +/** + * A macro to retrieve the type of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorType for `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) -#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) -#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) -#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) -#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) -#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) +/** + * A macro to retrieve the range of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorRange of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) + +/** + * A macro to retrieve the chroma sample location of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ChromaLocation of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) + +/** + * A macro to retrieve the primaries of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorPrimaries of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) + +/** + * A macro to retrieve the transfer characteristics of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_TransferCharacteristics of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) + +/** + * A macro to retrieve the matrix coefficients of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_MatrixCoefficients of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) + +/** + * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix + * coefficients. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT601 or BT470BG, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) + +/** + * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) + +/** + * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix + * coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT2020_NCL, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) + +/** + * A macro to determine if an SDL_Colorspace has a limited range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if limited range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) + +/** + * A macro to determine if an SDL_Colorspace has a full range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if full range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. @@ -544,7 +997,7 @@ typedef enum SDL_ChromaLocation * function, etc.), this is not an exhaustive list, but rather a * representative sample of the kinds of colorspaces supported in SDL. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_ColorPrimaries * \sa SDL_ColorRange @@ -631,7 +1084,7 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ - SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, SDL_COLOR_RANGE_FULL, SDL_COLOR_PRIMARIES_BT2020, @@ -639,15 +1092,10 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ } SDL_Colorspace; - -/* The default colorspace for RGB surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB - -/* The default colorspace for YUV surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG - /** * A structure that represents a color as RGBA components. * @@ -656,7 +1104,7 @@ typedef enum SDL_Colorspace * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Color { @@ -670,7 +1118,7 @@ typedef struct SDL_Color * The bits of this structure can be directly reinterpreted as a float-packed * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_FColor { @@ -683,7 +1131,7 @@ typedef struct SDL_FColor /** * A set of indexed colors representing a palette. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -698,7 +1146,7 @@ typedef struct SDL_Palette /** * Details about the format of a pixel. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PixelFormatDetails { @@ -729,7 +1177,7 @@ typedef struct SDL_PixelFormatDetails * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); @@ -742,16 +1190,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * \param Gmask a pointer filled in with the green mask for the format. * \param Bmask a pointer filled in with the blue mask for the format. * \param Amask a pointer filled in with the alpha mask for the format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatForMasks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); /** * Convert a bpp value and RGBA masks to an enumerated pixel format. @@ -769,7 +1217,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMasksForPixelFormat */ @@ -788,7 +1236,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); @@ -804,7 +1252,7 @@ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDet * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyPalette * \sa SDL_SetPaletteColors @@ -819,15 +1267,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); * \param colors an array of SDL_Color structures to copy into the palette. * \param firstcolor the index of the first palette entry to modify. * \param ncolors the number of entries to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); /** * Free a palette created with SDL_CreatePalette(). @@ -837,7 +1285,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette */ @@ -872,7 +1320,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB @@ -911,7 +1359,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -939,7 +1387,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -971,7 +1419,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform.h index bfdfa3a..e40f009 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,7 +51,7 @@ extern "C" { * \returns the name of the platform. If the correct platform name is not * available, returns a string beginning with the text "Unknown". * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform_defines.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform_defines.h index e7f91cf..7e9a0a9 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform_defines.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_platform_defines.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,180 +29,450 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 -#endif -#ifdef __NGAGE__ -#define SDL_PLATFORM_NGAGE 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ -#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif defined(HAVE_WINAPIFAMILY_H) && HAVE_WINAPIFAMILY_H + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT -#define SDL_PLATFORM_WINRT 1 +#error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_power.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_power.h index 1fdef78..4056ce3 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_power.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_power.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,15 @@ * # CategoryPower * * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ #include @@ -42,7 +51,7 @@ extern "C" { * * These are results returned by SDL_GetPowerInfo(). * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PowerState { @@ -80,7 +89,7 @@ typedef enum SDL_PowerState * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_process.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_process.h new file mode 100644 index 0000000..2cc7739 --- /dev/null +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_process.h @@ -0,0 +1,430 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used + * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set + * to `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value + * describing where standard error for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_properties.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_properties.h index c3a2c82..1f47d5f 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_properties.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_properties.h @@ -1,6 +1,6 @@ /* - Simple DiretMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -61,14 +61,14 @@ extern "C" { /** * SDL properties ID * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PropertiesID; /** * SDL property type * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PropertyType { @@ -86,7 +86,7 @@ typedef enum SDL_PropertyType * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); @@ -100,7 +100,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyProperties */ @@ -116,14 +116,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); * * \param src the properties to copy. * \param dst the destination properties. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** * Lock a group of properties. @@ -138,16 +138,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SD * thread. * * \param props the properties to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockProperties */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** * Unlock a group of properties. @@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockProperties */ @@ -180,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); * \threadsafety This callback may fire without any locks held; if this is a * concern, the app should provide its own locking. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetPointerPropertyWithCleanup */ @@ -204,18 +204,18 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \param cleanup the function to call when this property is deleted, or NULL * if no cleanup is necessary. * \param userdata a pointer that is passed to the cleanup function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_SetPointerProperty * \sa SDL_CleanupPropertyCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); /** * Set a pointer property in a group of properties. @@ -223,12 +223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_HasProperty @@ -238,7 +238,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \sa SDL_SetPointerPropertyWithCleanup * \sa SDL_SetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); /** * Set a string property in a group of properties. @@ -249,16 +249,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID pro * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** * Set an integer property in a group of properties. @@ -266,16 +266,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumberProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** * Set a floating point property in a group of properties. @@ -283,16 +283,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetFloatProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** * Set a boolean property in a group of properties. @@ -300,31 +300,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); /** * Return whether a property exists in a group of properties. * * \param props the properties to query. * \param name the name of the property to query. - * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. + * \returns true if the property exists, or false if it doesn't. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** * Get the type of a property in a group of properties. @@ -336,7 +336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasProperty */ @@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty * \sa SDL_GetFloatProperty @@ -391,7 +391,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -413,7 +413,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -435,7 +435,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -457,27 +457,27 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty * \sa SDL_SetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); /** * Clear a property from a group of properties. * * \param props the properties to modify. * \param name the name of the property to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); /** * A callback used to enumerate all the properties in a group of properties. @@ -492,7 +492,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, c * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this * callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EnumerateProperties */ @@ -507,14 +507,14 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop * \param props the properties to query. * \param callback the function to call for each property. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** * Destroy a group of properties. @@ -528,7 +528,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID pr * locked or other threads might be setting or getting values * from these properties. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_rect.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_rect.h index ea97df9..8998de6 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_rect.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_rect.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,7 +23,7 @@ * # CategoryRect * * Some helper functions for managing rectangles and 2D points, in both - * interger and floating point versions. + * integer and floating point versions. */ #ifndef SDL_rect_h_ @@ -41,7 +41,7 @@ extern "C" { /** * The structure that defines a point (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect @@ -55,7 +55,7 @@ typedef struct SDL_Point /** * The structure that defines a point (using floating point values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat @@ -70,7 +70,7 @@ typedef struct SDL_FPoint /** * A rectangle, with the origin at the upper left (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmpty * \sa SDL_RectsEqual @@ -91,7 +91,7 @@ typedef struct SDL_Rect * A rectangle, with the origin at the upper left (using floating point * values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -121,7 +121,7 @@ typedef struct SDL_FRect * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) { @@ -146,16 +146,16 @@ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) { return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; } /** @@ -170,15 +170,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) { - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; } /** @@ -194,51 +194,51 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) { return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; + (a->w == b->w) && (a->h == b->h)) ? true : false; } /** * Determine whether two rectangles intersect. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); /** * Calculate the intersection of two rectangles. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate the union of two rectangles. @@ -247,12 +247,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate a minimal rectangle enclosing a set of points. @@ -266,12 +266,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const S * \param clip an SDL_Rect used for clipping or NULL to enclose all points. * \param result an SDL_Rect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); /** * Calculate the intersection of a rectangle and line segment. @@ -287,11 +287,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); /* SDL_FRect versions... */ @@ -311,16 +311,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Re * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) { return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && - (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; } /** @@ -335,15 +335,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) { - return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; } /** @@ -363,22 +363,22 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * \param a the first rectangle to test. * \param b the second rectangle to test. * \param epsilon the epsilon value for comparison. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualFloat */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) { return (a && b && ((a == b) || ((SDL_fabsf(a->x - b->x) <= epsilon) && (SDL_fabsf(a->y - b->y) <= epsilon) && (SDL_fabsf(a->w - b->w) <= epsilon) && (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; + ? true : false; } /** @@ -398,15 +398,15 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualEpsilon */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) { return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); } @@ -414,34 +414,34 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec /** * Determine whether two rectangles intersect with float precision. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); /** * Calculate the intersection of two rectangles with float precision. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersectionFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate the union of two rectangles with float precision. @@ -450,12 +450,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate a minimal rectangle enclosing a set of points with float @@ -470,12 +470,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, c * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); /** * Calculate the intersection of a rectangle and line segment with float @@ -492,11 +492,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_render.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_render.h index 706308c..891e994 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_render.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_render.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -40,8 +40,8 @@ * * This API is designed to accelerate simple 2D operations. You may want more * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. + * should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the + * many good 3D engines. * * These functions must be called from the main thread. See this bug for * details: https://github.com/libsdl-org/SDL/issues/986 @@ -51,10 +51,13 @@ #define SDL_render_h_ #include +#include #include #include +#include #include #include +#include #include #include @@ -66,14 +69,14 @@ extern "C" { /** * The name of the software renderer. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_SOFTWARE_RENDERER "software" /** * Vertex structure. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Vertex { @@ -85,7 +88,7 @@ typedef struct SDL_Vertex /** * The access pattern allowed for a texture. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TextureAccess { @@ -97,7 +100,7 @@ typedef enum SDL_TextureAccess /** * How the logical size is mapped to the output. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_RendererLogicalPresentation { @@ -111,15 +114,32 @@ typedef enum SDL_RendererLogicalPresentation /** * A structure representing rendering state * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Renderer SDL_Renderer; +#ifndef SDL_INTERNAL + /** * An efficient driver-specific representation of pixel data * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ @@ -135,7 +155,9 @@ typedef struct SDL_Texture SDL_Texture; * * \returns the number of built in render drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_GetRenderDriver @@ -158,7 +180,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * \returns the name of the rendering driver at the requested index, or NULL * if an invalid index was specified. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumRenderDrivers */ @@ -174,36 +198,43 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * SDL_CreateWindow()). * \param window a pointer filled with the window, or NULL on error. * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); /** * Create a 2D rendering context for a window. * * If you want a specific renderer, you can specify its name here. A list of - * available renderers can be obtained by calling SDL_GetRenderDriver multiple - * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't - * need a specific renderer, specify NULL and SDL will attempt to choose the - * best option for you, based on what is available on the user's system. + * available renderers can be obtained by calling SDL_GetRenderDriver() + * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you + * don't need a specific renderer, specify NULL and SDL will attempt to choose + * the best option for you, based on what is available on the user's system. + * + * If `name` is a comma-separated list, SDL will try each name, in the order + * listed, until one succeeds or all of them fail. * * By default the rendering size matches the window size in pixels, but you * can call SDL_SetRenderLogicalPresentation() to change the content size and * scaling options. * * \param window the window where rendering is displayed. - * \param name the name of the rendering driver to initialize, or NULL to - * initialize the first one supporting the requested flags. + * \param name the name of the rendering driver to initialize, or NULL to let + * SDL choose one. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRendererWithProperties * \sa SDL_CreateSoftwareRenderer @@ -225,7 +256,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * displayed, required if this isn't a software renderer using a surface * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering * is displayed, if you want a software renderer without a window - * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace + * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace * value describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and @@ -255,7 +286,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateRenderer @@ -290,7 +323,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRenderer */ @@ -303,7 +338,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surfac * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); @@ -314,7 +351,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); @@ -325,7 +364,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende * \returns the name of the selected renderer, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateRendererWithProperties @@ -348,21 +389,21 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN, * representing the available texture formats for this renderer. - * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with * HDR enabled. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is * automatically multiplied into the color scale. This property can change - * dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range * that can be displayed, in terms of the SDR white point. When HDR is not * enabled, this will be 1.0. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * * With the direct3d renderer: * @@ -403,11 +444,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * swapchain images, or potential frames in flight, used by the Vulkan * renderer * + * With the gpu renderer: + * + * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with + * the renderer + * * \param renderer the rendering context. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); @@ -434,6 +482,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende #define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count" +#define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device" /** * Get the output size in pixels of a rendering context. @@ -444,14 +493,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \param renderer the rendering context. * \param w a pointer filled in with the width in pixels. * \param h a pointer filled in with the height in pixels. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Get the current output size in pixels of a rendering context. @@ -464,28 +515,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *rende * \param renderer the rendering context. * \param w a pointer filled in with the current width. * \param h a pointer filled in with the current height. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Create a texture for a rendering context. * + * The contents of a texture when first created are not defined. + * * \param renderer the rendering context. * \param format one of the enumerated values in SDL_PixelFormat. * \param access one of the enumerated values in SDL_TextureAccess. * \param w the width of the texture in pixels. * \param h the height of the texture in pixels. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTextureFromSurface * \sa SDL_CreateTextureWithProperties @@ -513,7 +569,9 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureWithProperties @@ -526,7 +584,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * These are the supported properties: * - * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for @@ -617,11 +675,12 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * \param renderer the rendering context. * \param props the properties to use. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateTexture @@ -661,7 +720,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * The following read-only properties are provided by SDL: * - * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing + * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing * the texture colorspace. * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in * SDL_PixelFormat. @@ -701,14 +760,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * With the vulkan renderer: * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_POINTER`: the VkImage associated with - * the texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_U_POINTER`: the VkImage associated with - * the U plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_V_POINTER`: the VkImage associated with - * the V plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_UV_POINTER`: the VkImage associated with - * the UV plane of a NV12/NV21 texture + * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the + * texture * * With the opengl renderer: * @@ -740,16 +793,13 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc) * - * With the vulkan renderer: - * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the - * texture - * * \param texture the texture to query. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); @@ -789,7 +839,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Textur * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture); @@ -801,12 +851,14 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This * argument can be NULL if you don't need this information. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); /** * Set an additional color value multiplied into render copy operations. @@ -818,22 +870,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, fl * `srcC = srcC * (color / 255)` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); /** @@ -846,22 +900,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture * `srcC = srcC * color` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); /** @@ -871,16 +927,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *te * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); /** * Get the additional color value multiplied into render copy operations. @@ -889,16 +947,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); /** * Set an additional alpha value multiplied into render copy operations. @@ -909,20 +969,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *te * `srcA = srcA * (alpha / 255)` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); /** * Set an additional alpha value multiplied into render copy operations. @@ -933,83 +995,93 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture * `srcA = srcA * alpha` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); /** * Set the blend mode for a texture, used by SDL_RenderTexture(). * * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. + * and this function returns false. * * \param texture the texture to update. * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); /** * Get the blend mode used for texture copy operations. * * \param texture the texture to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); /** * Set the scale mode used for texture scale operations. @@ -1020,28 +1092,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *textur * * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); /** * Get the scale mode used for texture scale operations. * * \param texture the texture to query. * \param scaleMode a pointer filled in with the current scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); /** * Update the given texture rectangle with new pixel data. @@ -1063,17 +1139,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *textur * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding * between lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture * \sa SDL_UpdateNVTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); /** * Update a rectangle within a planar YV12 or IYUV texture with new pixel @@ -1095,15 +1173,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, con * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateNVTexture * \sa SDL_UpdateTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, @@ -1125,15 +1205,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \param UVplane the raw pixel data for the UV plane. * \param UVpitch the number of bytes between rows of pixel data for the UV * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch); @@ -1157,16 +1239,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the * pitch is the length of one row in bytes. - * \returns SDL_TRUE on success or SDL_FALSE if the texture is not valid or - * was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. + * \returns true on success or false if the texture is not valid or was not + * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTextureToSurface * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch); @@ -1192,17 +1276,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** * Unlock a texture, uploading the changes to video memory, if needed. @@ -1217,7 +1303,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *textu * * \param texture a texture locked by SDL_LockTexture(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture */ @@ -1234,14 +1322,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderTarget */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** * Get the current render target. @@ -1252,7 +1342,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderTarget */ @@ -1261,13 +1353,23 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend /** * Set a device independent resolution and presentation mode for rendering. * - * This function sets the width and height of the logical rendering output. A - * render target is created at the specified size and used for rendering and - * then copied to the output during presentation. + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the window is always the requested dimensions, + * scaling to the actual window resolution as necessary. + * + * This can be useful for games that expect a fixed size, but would like to + * scale the output to whatever is available, regardless of how a user resizes + * a window, or if the display is high DPI. * * You can disable logical coordinates by setting the mode to * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel - * resolution of the output window. + * resolution of the output window; it is safe to toggle logical presentation + * during the rendering of a frame: perhaps most of the rendering is done to + * specific dimensions but to make fonts look sharp, the app turns off logical + * presentation while drawing text. + * + * Letterboxing will only happen if logical presentation is enabled during + * SDL_RenderPresent; be sure to reenable it first if you were using it. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). @@ -1276,17 +1378,18 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \param w the width of the logical resolution. * \param h the height of the logical resolution. * \param mode the presentation mode used. - * \param scale_mode the scale mode used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertEventToRenderCoordinates * \sa SDL_GetRenderLogicalPresentation * \sa SDL_GetRenderLogicalPresentationRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); /** * Get device independent resolution and presentation mode for rendering. @@ -1297,16 +1400,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param w an int to be filled with the width. * \param h an int to be filled with the height. - * \param mode a pointer filled in with the presentation mode. - * \param scale_mode a pointer filled in with the scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); /** * Get the final presentation rectangle for rendering. @@ -1319,36 +1423,54 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param rect a pointer filled in with the final presentation rectangle, may * be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); /** * Get a point in render coordinates when given a point in window coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param window_x the x coordinate in window coordinates. * \param window_y the y coordinate in window coordinates. * \param x a pointer filled with the x coordinate in render coordinates. * \param y a pointer filled with the y coordinate in render coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); /** * Get a point in window coordinates when given a point in render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param x the x coordinate in render coordinates. * \param y the y coordinate in render coordinates. @@ -1356,65 +1478,95 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Rendere * coordinates. * \param window_y a pointer filled with the y coordinate in window * coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); /** * Convert the coordinates in an event to render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * Various event types are converted with this function: mouse, touch, pen, + * etc. + * * Touch coordinates are converted from normalized coordinates in the window * to non-normalized rendering coordinates. * - * Once converted, the coordinates may be outside the rendering area. + * Relative mouse coordinates (xrel and yrel event fields) are _also_ + * converted. Applications that do not want these fields converted should use + * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of + * converting the entire event structure. + * + * Once converted, coordinates may be outside the rendering area. * * \param renderer the rendering context. * \param event the event to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderCoordinatesFromWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); /** * Set the drawing area for rendering on the current target. * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL * to set the viewport to the entire target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_RenderViewportSet */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the drawing area for the current target. * * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current drawing area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderViewportSet * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); /** * Return whether an explicit rectangle was set as the viewport. @@ -1424,15 +1576,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *rendere * viewport is always reset when changing rendering targets. * * \param renderer the rendering context. - * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target). + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); /** * Get the safe area for rendering within the current viewport. @@ -1447,12 +1601,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect a pointer filled in with the area that is safe for interactive * content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); /** * Set the clip rectangle for rendering on the specified target. @@ -1460,15 +1616,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the clip area, relative to * the viewport, or NULL to disable clipping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_RenderClipEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the clip rectangle for the current target. @@ -1476,29 +1634,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current clipping area * or an empty rectangle if clipping is disabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderClipEnabled * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); /** * Get whether clipping is enabled on the given renderer. * * \param renderer the rendering context. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. + * \returns true if clipping is enabled or false if not; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); /** * Set the drawing scale for rendering on the current target. @@ -1514,14 +1676,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * \param renderer the rendering context. * \param scaleX the horizontal scaling factor. * \param scaleY the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); /** * Get the drawing scale for the current target. @@ -1529,14 +1693,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, * \param renderer the rendering context. * \param scaleX a pointer filled in with the horizontal scaling factor. * \param scaleY a pointer filled in with the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); /** * Set the color used for drawing operations. @@ -1551,15 +1717,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to * specify how the alpha channel is used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColor * \sa SDL_SetRenderDrawColorFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Set the color used for drawing operations (Rect, Line and Clear). @@ -1574,15 +1742,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *render * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is * used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1596,15 +1766,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *r * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1618,15 +1790,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *render * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColorFloat * \sa SDL_GetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); /** * Set the color scale used for render operations. @@ -1641,28 +1815,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *r * * \param renderer the rendering context. * \param scale the color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); /** * Get the color scale used for render operations. * * \param renderer the rendering context. * \param scale a pointer filled in with the current color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); /** * Set the blend mode used for drawing operations (Fill and Line). @@ -1671,28 +1849,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *rende * * \param renderer the rendering context. * \param blendMode the SDL_BlendMode to use for blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); /** * Get the blend mode used for drawing operations. * * \param renderer the rendering context. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); /** * Clear the current rendering target with the drawing color. @@ -1703,14 +1885,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *re * SDL_SetRenderDrawColor() when needed. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. @@ -1718,14 +1902,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \param renderer the renderer which should draw a point. * \param x the x coordinate of the point. * \param y the y coordinate of the point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); /** * Draw multiple points on the current rendering target at subpixel precision. @@ -1733,14 +1919,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, flo * \param renderer the renderer which should draw multiple points. * \param points the points to draw. * \param count the number of points to draw. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a line on the current rendering target at subpixel precision. @@ -1750,14 +1938,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, co * \param y1 the y coordinate of the start point. * \param x2 the x coordinate of the end point. * \param y2 the y coordinate of the end point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLines */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); /** * Draw a series of connected lines on the current rendering target at @@ -1766,14 +1956,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, floa * \param renderer the renderer which should draw multiple lines. * \param points the points along the lines. * \param count the number of points, drawing count-1 lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLine */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a rectangle on the current rendering target at subpixel precision. @@ -1781,14 +1973,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, con * \param renderer the renderer which should draw a rectangle. * \param rect a pointer to the destination rectangle, or NULL to outline the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Draw some number of rectangles on the current rendering target at subpixel @@ -1797,14 +1991,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, cons * \param renderer the renderer which should draw multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Fill a rectangle on the current rendering target with the drawing color at @@ -1813,14 +2009,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, con * \param renderer the renderer which should fill a rectangle. * \param rect a pointer to the destination rectangle, or NULL for the entire * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Fill some number of rectangles on the current rendering target with the @@ -1829,14 +2027,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, * \param renderer the renderer which should fill multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Copy a portion of the texture to the current rendering target at subpixel @@ -1848,15 +2048,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, * texture. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTextureRotated * \sa SDL_RenderTextureTiled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); /** * Copy a portion of the source texture to the current rendering target, with @@ -1875,17 +2077,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, S * around dstrect.w/2, dstrect.h/2). * \param flip an SDL_FlipMode value stating which flipping actions should be * performed on the texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, - const double angle, const SDL_FPoint *center, - const SDL_FlipMode flip); + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); + +/** + * Copy a portion of the source texture to the current rendering target, with + * affine transform, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param origin a pointer to a point indicating where the top-left corner of + * srcrect should be mapped to, or NULL for the rendering + * target's origin. + * \param right a pointer to a point indicating where the top-right corner of + * srcrect should be mapped to, or NULL for the rendering + * target's top-right corner. + * \param down a pointer to a point indicating where the bottom-left corner of + * srcrect should be mapped to, or NULL for the rendering target's + * bottom-left corner. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FPoint *origin, + const SDL_FPoint *right, const SDL_FPoint *down); /** * Tile a portion of the texture to the current rendering target at subpixel @@ -1903,14 +2137,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *rend * 64x64 tiles. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); /** * Perform a scaled copy using the 9-grid algorithm to the current rendering @@ -1935,14 +2171,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *render * corner of `dstrect`, or 0.0f for an unscaled copy. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); /** * Render a list of triangles, optionally using a texture and indices into the @@ -1957,14 +2195,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *render * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices number of indices. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometryRaw */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices); @@ -1987,14 +2227,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * if NULL all vertices will be rendered in sequential order. * \param num_indices number of indices. * \param size_indices index size: 1 (byte), 2 (short), 4 (int). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometry */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, @@ -2017,7 +2259,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *rendere * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); @@ -2041,18 +2285,20 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * pixel. * * Please note, that in case of rendering to a texture - there is **no need** - * to call `SDL_RenderPresent` after drawing needed objects to a texture, you - * are only required to change back the rendering target to default via - * `SDL_SetRenderTarget(renderer, NULL)` afterwards, as textures by themselves - * do not have a concept of backbuffers. + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \threadsafety You may only call this function on the main thread. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_RenderClear @@ -2067,7 +2313,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \sa SDL_SetRenderDrawBlendMode * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); /** * Destroy the specified texture. @@ -2077,7 +2323,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureFromSurface @@ -2092,7 +2340,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer */ @@ -2122,12 +2372,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * be prepared to make changes if specific state needs to be protected. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); /** * Get the CAMetalLayer associated with the given Metal renderer. @@ -2139,7 +2391,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalCommandEncoder */ @@ -2160,7 +2414,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalLayer */ @@ -2187,15 +2443,15 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not * needed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is **NOT** safe to call this function from two threads at * once. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); /** * Toggle VSync of the given renderer. @@ -2204,21 +2460,23 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer * * The `vsync` parameter can be 1 to synchronize present with every vertical * refresh, 2 to synchronize present with every second vertical refresh, etc., - * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), - * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is - * supported by every driver, so you should check the return value to see - * whether the requested setting is supported. + * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or + * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by + * every driver, so you should check the return value to see whether the + * requested setting is supported. * * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); #define SDL_RENDERER_VSYNC_DISABLED 0 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1) @@ -2229,14 +2487,96 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, * \param renderer the renderer to toggle. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetRenderVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); + +/** + * The size, in pixels, of a single SDL_RenderDebugText() character. + * + * The font is monospaced and square, so this applies to all characters. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + */ +#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8 + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a string of text to an SDL_Renderer. Note that + * this is a convenience function for debugging, with severe limitations, and + * not intended to be used for production apps and games. + * + * Among these limitations: + * + * - It accepts UTF-8 strings, but will only renders ASCII characters. + * - It has a single, tiny size (8x8 pixels). One can use logical presentation + * or scaling to adjust it, but it will be blurry. + * - It uses a simple, hardcoded bitmap font. It does not allow different font + * selections and it does not support truetype, for proper scaling. + * - It does no word-wrapping and does not treat newline characters as a line + * break. If the text goes out of the window, it's gone. + * + * For serious text rendering, there are several good options, such as + * SDL_ttf, stb_truetype, or other external libraries. + * + * On first use, this will create an internal texture for rendering glyphs. + * This texture will live until the renderer is destroyed. + * + * The text is drawn in the color specified by SDL_SetRenderDrawColor(). + * + * \param renderer the renderer which should draw a line of text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param str the string to render. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugTextFormat + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str); + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a printf()-style format string to a renderer. + * Note that this is a convinence function for debugging, with severe + * limitations, and is not intended to be used for production apps and games. + * + * For the full list of limitations and other useful information, see + * SDL_RenderDebugText. + * + * \param renderer the renderer which should draw the text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param fmt the format string to draw. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_revision.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_revision.h index f78e5d9..18f7c4d 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_revision.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_revision.h @@ -1,22 +1,22 @@ /* - Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga - 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. + 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: + 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. + 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. */ /* WIKI CATEGORY: Version */ @@ -48,9 +48,9 @@ */ #define SDL_REVISION "Some arbitrary string decided at SDL build time" #elif defined(SDL_VENDOR_INFO) -#define SDL_REVISION SDL_VENDOR_INFO +#define SDL_REVISION "release-3.2.0-0-g535d80bad (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "" +#define SDL_REVISION "release-3.2.0-0-g535d80bad" #endif #endif /* SDL_revision_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_scancode.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_scancode.h index ccf8bb5..9650a6c 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_scancode.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_scancode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryScancode * * Defines keyboard scancodes. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_scancode_h_ @@ -42,7 +47,7 @@ * The values in this enumeration are based on the USB usage page standard: * https://usb.org/sites/default/files/hut1_5.pdf * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_Scancode { @@ -417,8 +422,8 @@ typedef enum SDL_Scancode SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_sensor.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_sensor.h index 3ae4856..b220f05 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_sensor.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_sensor.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategorySensor * * SDL sensor management. + * + * These APIs grant access to gyros and accelerometers on various platforms. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ @@ -41,14 +47,10 @@ extern "C" { #endif /** - * SDL_sensor.h + * The opaque structure used to identify an opened SDL sensor. * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system - * for sensors, and load appropriate drivers. + * \since This struct is available since SDL 3.2.0. */ - -struct SDL_Sensor; typedef struct SDL_Sensor SDL_Sensor; /** @@ -57,7 +59,7 @@ typedef struct SDL_Sensor SDL_Sensor; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SensorID; @@ -69,7 +71,7 @@ typedef Uint32 SDL_SensorID; * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the * earth, which is a positive Y value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_STANDARD_GRAVITY 9.80665f @@ -123,7 +125,7 @@ typedef Uint32 SDL_SensorID; * * The gyroscope axis data is not changed when the device is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayOrientation */ @@ -151,7 +153,7 @@ typedef enum SDL_SensorType * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); @@ -163,7 +165,7 @@ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); * \param instance_id the sensor instance ID. * \returns the sensor name, or NULL if `instance_id` is not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id); @@ -176,7 +178,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID ins * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is * not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID instance_id); @@ -189,7 +191,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID i * \returns the sensor platform dependent type, or -1 if `instance_id` is not * valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); @@ -200,7 +202,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id); @@ -211,7 +213,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); @@ -222,7 +224,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instan * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); @@ -233,7 +235,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor * \returns the sensor name or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); @@ -244,7 +246,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor); @@ -254,7 +256,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor) * \param sensor the SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor); @@ -265,7 +267,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor) * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); @@ -277,19 +279,19 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); * \param sensor the SDL_Sensor object to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** * Close a sensor previously opened with SDL_OpenSensor(). * * \param sensor the SDL_Sensor object to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); @@ -302,7 +304,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); * This needs to be called from the thread that initialized the sensor * subsystem. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateSensors(void); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_stdinc.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_stdinc.h index 5539f2a..4e15a3c 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_stdinc.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_stdinc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,25 @@ /** * # CategoryStdinc * - * This is a general header that includes C language support. It implements a - * subset of the C runtime: these should all behave the same way as their C - * runtime equivalents, but with an SDL_ prefix. + * SDL provides its own implementation of some of the most important C runtime + * functions. + * + * Using these functions allows an app to have access to common C + * functionality without depending on a specific C runtime (or a C runtime at + * all). More importantly, the SDL implementations work identically across + * platforms, so apps can avoid surprises like snprintf() behaving differently + * between Windows and Linux builds, or itoa() only existing on some + * platforms. + * + * For many of the most common functions, like SDL_memcpy, SDL might just call + * through to the usual C runtime behind the scenes, if it makes sense to do + * so (if it's faster and always available/reliable on a given platform), + * reducing library size and offering the most optimized option. + * + * SDL also offers other C-runtime-adjacent functionality in this header that + * either isn't, strictly speaking, part of any C runtime standards, like + * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better + * options, like SDL_strlcpy(), which functions as a safer form of strcpy(). */ #ifndef SDL_stdinc_h_ @@ -32,17 +48,34 @@ #include -#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -#include -#endif #include -#ifndef __cplusplus -#include -#endif #include #include #include +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H) +#if __has_include() +#define SDL_INCLUDE_STDBOOL_H +#endif +#endif +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + #ifndef SDL_DISABLE_ALLOCA # ifndef alloca # ifdef HAVE_ALLOCA_H @@ -74,31 +107,120 @@ void *alloca(size_t); # endif #endif -#ifdef SIZE_MAX + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Don't let SDL use "long long" C types. + * + * SDL will define this if it believes the compiler doesn't understand the + * "long long" syntax for C datatypes. This can happen on older compilers. + * + * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it + * is safe to define this yourself to build against the SDL headers. + * + * If this is defined, it will remove access to some C runtime support + * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype + * explicitly. The rest of SDL will still be available. + * + * SDL's own source code cannot be built with a compiler that has this + * defined, for various technical reasons. + */ +#define SDL_NOLONGLONG 1 + +#elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */ +# define SDL_NOLONGLONG 1 +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The largest value that a `size_t` can hold for the target platform. + * + * `size_t` is generally the same size as a pointer in modern times, but this + * can get weird on very old and very esoteric machines. For example, on a + * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment + * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with + * the offset into an individual segment. + * + * In modern times, it's generally expected to cover an entire linear address + * space. But be careful! + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SIZE_MAX SIZE_MAX + +#elif defined(SIZE_MAX) # define SDL_SIZE_MAX SIZE_MAX #else # define SDL_SIZE_MAX ((size_t) -1) #endif +#ifndef SDL_COMPILE_TIME_ASSERT +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + /** - * Check if the compiler supports a given builtin. - * Supported by virtually all clang versions and recent gcc. Use this - * instead of checking the clang version if possible. + * A compile-time assertion. + * + * This can check constant values _known to the compiler at build time_ for + * correctness, and end the compile with the error if they fail. + * + * Often times these are used to verify basic truths, like the size of a + * datatype is what is expected: + * + * ```c + * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); + * ``` + * + * The `name` parameter must be a valid C symbol, and must be unique across + * all compile-time asserts in the same compilation unit (one run of the + * compiler), or the build might fail with cryptic errors on some targets. + * This is used with a C language trick that works on older compilers that + * don't support better assertion techniques. + * + * If you need an assertion that operates at runtime, on variable data, you + * should try SDL_assert instead. + * + * \param name a unique identifier for this assertion. + * \param x the value to test. Must be a boolean value. + * + * \threadsafety This macro doesn't generate any code to run. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_assert */ -#ifdef __has_builtin -#define SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define SDL_HAS_BUILTIN(x) 0 +#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x) +#elif defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] #endif /** - * The number of elements in an array. + * The number of elements in a static array. + * + * This will compile but return incorrect results for a pointer to an array; + * it has to be an array the compiler knows the size of. * * This macro looks like it double-evaluates the argument, but it does so * inside of `sizeof`, so there are no side-effects here, as expressions do * not actually run any code in these cases. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) @@ -111,7 +233,9 @@ void *alloca(size_t); * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * ``` * - * \since This macro is available since SDL 3.0.0. + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -122,7 +246,76 @@ void *alloca(size_t); * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). */ /* @{ */ -#ifdef __cplusplus + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) #define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) #define SDL_static_cast(type, expression) static_cast(expression) #define SDL_const_cast(type, expression) const_cast(expression) @@ -131,9 +324,23 @@ void *alloca(size_t); #define SDL_static_cast(type, expression) ((type)(expression)) #define SDL_const_cast(type, expression) ((type)(expression)) #endif + /* @} *//* Cast operators */ -/* Define a four character code as a Uint32 */ +/** + * Define a four character code as a Uint32. + * + * \param A the first ASCII character. + * \param B the second ASCII character. + * \param C the third ASCII character. + * \param D the fourth ASCII character. + * \returns the four characters converted into a Uint32, one character + * per-byte. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FOURCC(A, B, C, D) \ ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ @@ -149,7 +356,7 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -162,63 +369,49 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ -#elif defined(INT64_C) +#else /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +#ifndef SDL_SINT64_C +#if defined(INT64_C) #define SDL_SINT64_C(c) INT64_C(c) -#define SDL_UINT64_C(c) UINT64_C(c) #elif defined(_MSC_VER) #define SDL_SINT64_C(c) c ## i64 -#define SDL_UINT64_C(c) c ## ui64 #elif defined(__LP64__) || defined(_LP64) #define SDL_SINT64_C(c) c ## L -#define SDL_UINT64_C(c) c ## UL #else #define SDL_SINT64_C(c) c ## LL +#endif +#endif /* !SDL_SINT64_C */ + +#ifndef SDL_UINT64_C +#if defined(UINT64_C) +#define SDL_UINT64_C(c) UINT64_C(c) +#elif defined(_MSC_VER) +#define SDL_UINT64_C(c) c ## ui64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_UINT64_C(c) c ## UL +#else #define SDL_UINT64_C(c) c ## ULL #endif +#endif /* !SDL_UINT64_C */ + +#endif /* !SDL_WIKI_DOCUMENTATION_SECTION */ /** * \name Basic data types */ /* @{ */ -/** - * A boolean false. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_FALSE false - -/** - * A boolean true. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_TRUE true - -/** - * A boolean type: true or false. - * - * \since This datatype is available since SDL 3.0.0. - * - * \sa SDL_TRUE - * \sa SDL_FALSE - */ -typedef bool SDL_bool; - /** * A signed 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ @@ -227,7 +420,7 @@ typedef int8_t Sint8; /** * An unsigned 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ @@ -236,7 +429,7 @@ typedef uint8_t Uint8; /** * A signed 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ @@ -245,7 +438,7 @@ typedef int16_t Sint16; /** * An unsigned 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ @@ -254,7 +447,7 @@ typedef uint16_t Uint16; /** * A signed 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ @@ -263,7 +456,7 @@ typedef int32_t Sint32; /** * An unsigned 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ @@ -272,7 +465,7 @@ typedef uint32_t Uint32; /** * A signed 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ @@ -283,7 +476,7 @@ typedef int64_t Sint64; /** * An unsigned 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -299,7 +492,7 @@ typedef uint64_t Uint64; * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with * SDL_TimeToWindows() and SDL_TimeFromWindows(). * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_MAX_SINT64 * \sa SDL_MIN_SINT64 @@ -325,40 +518,217 @@ typedef Sint64 SDL_Time; * Equals by default to platform-defined `FLT_EPSILON`, or * `1.1920928955078125e-07F` if that's not available. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ #endif /* @} *//* Floating-point constants */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A printf-formatting string for an Sint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs64 "lld" + +/** + * A printf-formatting string for a Uint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu64 "llu" + +/** + * A printf-formatting string for a Uint64 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx64 "llx" + +/** + * A printf-formatting string for a Uint64 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX64 "llX" + +/** + * A printf-formatting string for an Sint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs32 "d" + +/** + * A printf-formatting string for a Uint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu32 "u" + +/** + * A printf-formatting string for a Uint32 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx32 "x" + +/** + * A printf-formatting string for a Uint32 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX32 "X" + +/** + * A printf-formatting string prefix for a `long long` value. + * + * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu, + * SDL_PRILLx, or SDL_PRILLX instead. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILL_PREFIX "ll" + +/** + * A printf-formatting string for a `long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLd SDL_PRILL_PREFIX "d" + +/** + * A printf-formatting string for a `unsigned long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLu SDL_PRILL_PREFIX "u" + +/** + * A printf-formatting string for an `unsigned long long` value as lower-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLx SDL_PRILL_PREFIX "x" + +/** + * A printf-formatting string for an `unsigned long long` value as upper-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* SDL_WIKI_DOCUMENTATION_SECTION */ + /* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. + * should define these but this is not true all platforms. * (for example win32) */ #ifndef SDL_PRIs64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIs64 "I64d" -#elif defined(PRIs64) -#define SDL_PRIs64 PRIs64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(PRId64) +#define SDL_PRIs64 PRId64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIs64 "ld" #else #define SDL_PRIs64 "lld" #endif #endif #ifndef SDL_PRIu64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIu64 "I64u" #elif defined(PRIu64) #define SDL_PRIu64 PRIu64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIu64 "lu" #else #define SDL_PRIu64 "llu" #endif #endif #ifndef SDL_PRIx64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIx64 "I64x" #elif defined(PRIx64) #define SDL_PRIx64 PRIx64 @@ -369,7 +739,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIX64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIX64 "I64X" #elif defined(PRIX64) #define SDL_PRIX64 PRIX64 @@ -407,9 +777,318 @@ typedef Sint64 SDL_Time; #define SDL_PRIX32 "X" #endif #endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#endif +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Macro that annotates function params with input buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + * ``` + * + * This notes that `src` should be `len` bytes in size and is only read by the + * function. The compiler or other analysis tools can warn when this doesn't + * appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) + +/** + * Macro that annotates function params with input/output string buffer size. + * + * If we were to annotate `strlcat`: + * + * ```c + * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + * ``` + * + * This notes that `dst` is a null-terminated C string, should be `maxlen` + * bytes in size, and is both read from and written to by the function. The + * compiler or other analysis tools can warn when this doesn't appear to be + * the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) + +/** + * Macro that annotates function params with output string buffer size. + * + * If we were to annotate `snprintf`: + * + * ```c + * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...); + * ``` + * + * This notes that `text` is a null-terminated C string, should be `maxlen` + * bytes in size, and is only written to by the function. The compiler or + * other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `wcsncpy`: + * + * ```c + * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` wchar_t in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for + * bytes. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_CAP(x) _Out_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) + +/** + * Macro that annotates function params with output buffer string size. + * + * If we were to annotate `strcpy`: + * + * ```c + * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and a zero-terminated string is written to it by the function. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +/** + * Macro that annotates function params as printf-style format strings. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a printf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ + +/** + * Macro that annotates function params as scanf-style format strings. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a scanf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ + +/** + * Macro that annotates a vararg function that operates like printf. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like printf. + * + * If we were to annotate `vfprintf`: + * + * ```c + * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like scanf. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by `...`. The compiler or other analysis tools can warn when this + * doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like scanf. + * + * If we were to annotate `vfscanf`: + * + * ```c + * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by a va_list. The compiler or other analysis tools can warn when + * this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like wprintf. + * + * If we were to annotate `fwprintf`: + * + * ```c + * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ + +/** + * Macro that annotates a va_list function that operates like wprintf. + * + * If we were to annotate `vfwprintf`: + * + * ```c + * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + +#elif defined(SDL_DISABLE_ANALYZE_MACROS) #define SDL_IN_BYTECAP(x) #define SDL_INOUT_Z_CAP(x) #define SDL_OUT_Z_CAP(x) @@ -423,7 +1102,7 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -447,53 +1126,45 @@ typedef Sint64 SDL_Time; #define SDL_PRINTF_FORMAT_STRING #define SDL_SCANF_FORMAT_STRING #endif -#ifdef __GNUC__ +#if defined(__GNUC__) || defined(__clang__) #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(bool, sizeof(SDL_bool) == 1); -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +#endif +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ /** \endcond */ @@ -523,7 +1194,96 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); extern "C" { #endif -#ifndef SDL_DISABLE_ALLOCA +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Allocate memory on the stack (maybe). + * + * If SDL knows how to access alloca() on the current platform, it will use it + * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to + * heap-allocate memory. + * + * Since this might not be stack memory at all, it's important that you check + * the returned pointer for NULL, and that you call SDL_stack_free on the + * memory when done with it. Since this might be stack memory, it's important + * that you don't allocate large amounts of it, or allocate in a loop without + * returning from the function, so the stack doesn't overflow. + * + * \param type the datatype of the memory to allocate. + * \param count the number of `type` objects to allocate. + * \returns newly-allocated memory, or NULL on failure. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_free + */ +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ +#define SDL_stack_free(data) +#elif !defined(SDL_DISABLE_ALLOCA) #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) #define SDL_stack_free(data) #else @@ -531,14 +1291,184 @@ extern "C" { #define SDL_stack_free(data) SDL_free(data) #endif +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If you want to allocate memory aligned to a specific alignment, consider + * using SDL_aligned_alloc(). + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void (SDLCALL *SDL_free_func)(void *mem); /** @@ -556,7 +1486,7 @@ typedef void (SDLCALL *SDL_free_func)(void *mem); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, @@ -575,7 +1505,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func * unlikely event of a background thread calling * SDL_SetMemoryFunctions simultaneously. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions @@ -599,42 +1529,42 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \param calloc_func custom calloc function. * \param realloc_func custom realloc function. * \param free_func custom free function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but one * should not replace the memory functions once any allocations * are made! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_calloc_func calloc_func, SDL_realloc_func realloc_func, SDL_free_func free_func); /** - * Allocate memory aligned to a specific value. - * - * If `alignment` is less than the size of `void *`, then it will be increased - * to match that. - * - * The returned memory address will be a multiple of the alignment value, and - * the amount of memory allocated will be a multiple of the alignment value. + * Allocate memory aligned to a specific alignment. * * The memory returned by this function must be freed with SDL_aligned_free(), - * and _not_ SDL_free. + * _not_ SDL_free(). * - * \param alignment the alignment requested. + * If `alignment` is less than the size of `void *`, it will be increased to + * match that. + * + * The returned memory address will be a multiple of the alignment value, and + * the size of the memory allocated will be a multiple of the alignment value. + * + * \param alignment the alignment of the memory. * \param size the size to allocate. - * \returns a pointer to the aligned memory. + * \returns a pointer to the aligned memory, or NULL if allocation failed. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_free */ @@ -646,11 +1576,13 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment * The pointer is no longer valid after this call and cannot be dereferenced * anymore. * - * \param mem a pointer previously returned by SDL_aligned_alloc. + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc */ @@ -659,31 +1591,552 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); /** * Get the number of outstanding (unfreed) allocations. * - * \returns the number of allocations. + * \returns the number of allocations or -1 if allocation counting is + * disabled. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); -extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); -extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); +/** + * Compute the absolute value of `x`. + * + * \param x an integer value. + * \returns the absolute value of x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); -/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ +/** + * Return the lesser of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) + +/** + * Return the greater of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `>` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) + +/** + * Return a value clamped to a range. + * + * If `x` is outside the range a values between `a` and `b`, the returned + * value will be `a` or `b` as appropriate. Otherwise, `x` is returned. + * + * This macro will produce incorrect results if `b` is less than `a`. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` and `>` operators. However, it double-evaluates all its parameters, so + * do not use expressions with side-effects here. + * + * \param x the value to compare. + * \param a the low end value. + * \param b the high end value. + * \returns x, clamped between a and b. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) /** @@ -697,7 +2150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); @@ -712,7 +2165,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); @@ -727,7 +2180,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); @@ -742,7 +2195,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); @@ -757,7 +2210,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); @@ -772,7 +2225,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); @@ -787,7 +2240,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isgraph * \sa SDL_isalnum @@ -812,7 +2265,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); @@ -827,7 +2280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); @@ -842,7 +2295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); @@ -861,7 +2314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); @@ -880,7 +2333,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isprint */ @@ -900,7 +2353,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); @@ -918,13 +2371,96 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); +/** + * Calculate a CRC-16 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-16 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-16 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); + +/** + * Calculate a CRC-32 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-32 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-32 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); +/** + * Calculate a 32-bit MurmurHash3 value for a block of data. + * + * https://en.wikipedia.org/wiki/MurmurHash + * + * A seed may be specified, which changes the final results consistently, but + * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous + * result from this function back into itself as the next seed value to + * calculate a hash in chunks; it won't produce the same hash as it would if + * the same data was provided in a single call. + * + * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not + * cryptographically secure, so it shouldn't be used for hashing top-secret + * data. + * + * \param data the data to be hashed. + * \param len the size of data, in bytes. + * \param seed a value that alters the final hash value. + * \returns a Murmur3 32-bit hash value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); + +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memmove + */ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memcpy */ @@ -935,10 +2471,52 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD #define SDL_memcpy memcpy #endif + +/** + * A macro to copy memory between objects, with basic type checking. + * + * SDL_memcpy and SDL_memmove do not care where you copy memory to and from, + * which can lead to bugs. This macro aims to avoid most of those bugs by + * making sure that the source and destination are both pointers to objects + * that are the same size. It does not check that the objects are the same + * _type_, just that the copy will not overflow either object. + * + * The size check happens at compile time, and the compiler will throw an + * error if the objects are different sizes. + * + * Generally this is intended to copy a single object, not an array. + * + * This macro looks like it double-evaluates its parameters, but the extras + * them are in `sizeof` sections, which generate no code nor side-effects. + * + * \param dst a pointer to the destination object. Must not be NULL. + * \param src a pointer to the source object. Must not be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ #define SDL_copyp(dst, src) \ { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) +/** + * Copy memory ranges that might overlap. + * + * It is okay for the memory regions to overlap. If you are confident that the + * regions never overlap, using SDL_memcpy() may improve performance. + * + * \param dst The destination memory region. Must not be NULL. + * \param src The source memory region. Must not be NULL. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memcpy + */ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memmove */ @@ -949,7 +2527,44 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, S #define SDL_memmove memmove #endif +/** + * Initialize all bytes of buffer of memory to a specific value. + * + * This function will set `len` bytes, pointed to by `dst`, to the value + * specified in `c`. + * + * Despite `c` being an `int` instead of a `char`, this only operates on + * bytes; `c` must be a value between 0 and 255, inclusive. + * + * \param dst the destination memory region. Must not be NULL. + * \param c the byte value to set. + * \param len the length, in bytes, to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); + +/** + * Initialize all 32-bit words of buffer of memory to a specific value. + * + * This function will set a buffer of `dwords` Uint32 values, pointed to by + * `dst`, to the value specified in `val`. + * + * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited + * to a range of 0-255. + * + * \param dst the destination memory region. Must not be NULL. + * \param val the Uint32 value to set. + * \param dwords the number of Uint32 values to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); /* Take advantage of compiler optimizations for memset */ @@ -960,18 +2575,255 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo #define SDL_memset memset #endif +/** + * Clear an object's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an object, not a pointer to an object, nor an array. + * + * \param x the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zerop + * \sa SDL_zeroa + */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) + +/** + * Clear an object's memory to zero, using a pointer. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires a pointer to an object, not an object itself, nor an array. + * + * \param x a pointer to the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) + +/** + * Clear an array's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the array size, so + * there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an array, not an object, nor a pointer to an object. + * + * \param x an array to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) + +/** + * Compare two buffers of memory. + * + * \param s1 the first buffer to compare. NULL is not permitted! + * \param s2 the second buffer to compare. NULL is not permitted! + * \param len the number of bytes to compare between the buffers. + * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is + * "greater than" s2, and zero if the buffers match exactly for `len` + * bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); +/** + * This works exactly like wcslen() but doesn't require access to a C runtime. + * + * Counts the number of wchar_t values in `wstr`, excluding the null + * terminator. + * + * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \returns the length (in wchar_t values, excluding the null terminator) of + * `wstr`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcsnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); + +/** + * This works exactly like wcsnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the + * null terminator. + * + * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * Also, `maxlen` is a count of wide characters, not bytes! + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \param maxlen The maximum amount of wide characters to count. + * \returns the length (in wide characters, excluding the null terminator) of + * `wstr` but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * Copy a wide string. + * + * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then + * appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` is 0, no wide characters are copied and no null terminator is + * written. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated wide string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcat + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \param src The second null-terminated wide string. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Allocate a copy of a wide string. + * + * This allocates enough space for a null-terminated copy of `wstr`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param wstr the string to copy. + * \returns a pointer to the newly-allocated wide string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); + +/** + * Search a wide string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); + +/** + * Search a wide string, up to n wide chars, for the first instance of a + * specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * value to end the string, or `maxlen` wide character have been examined. It + * is possible to use this function on a wide string without a null + * terminator. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \param maxlen the maximum number of wide characters to search in + * `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -989,7 +2841,7 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); @@ -1020,7 +2872,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); @@ -1050,7 +2902,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t * * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); @@ -1092,19 +2944,228 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); +/** + * This works exactly like strlen() but doesn't require access to a C runtime. + * + * Counts the bytes in `str`, excluding the null terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the length (in bytes, excluding the null terminator) of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); + +/** + * This works exactly like strnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null + * terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \param maxlen The maximum amount of bytes to count. + * \returns the length (in bytes, excluding the null terminator) of `src` but + * never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * Copy a string. + * + * This function copies up to `maxlen` - 1 characters from `src` to `dst`, + * then appends a null terminator. + * + * If `maxlen` is 0, no characters are copied and no null terminator is + * written. + * + * If you want to copy an UTF-8 string but need to ensure that multi-byte + * sequences are not truncated, consider using SDL_utf8strlcpy(). + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated string to copy. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param dst_bytes The length (in bytes) of the destination buffer. Must not + * be 0. + * \returns the number of bytes written, excluding the null terminator. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \param src The second null-terminated string. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of the + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Allocate a copy of a string. + * + * This allocates enough space for a null-terminated copy of `str`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); + +/** + * Allocate a copy of a string, up to n characters. + * + * This allocates enough space for a null-terminated copy of `str`, up to + * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into + * this space. + * + * If the string is longer than `maxlen` bytes, the returned string will be + * `maxlen` bytes long, plus a null-terminator character that isn't included + * in the count. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \param maxlen the maximum length of the copied string, not counting the + * null-terminator character. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); + +/** + * Reverse a string's contents. + * + * This reverses a null-terminated string in-place. Only the content of the + * string is reversed; the null-terminator character remains at the end of the + * reversed string. + * + * **WARNING**: This function reverses the _bytes_ of the string, not the + * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this + * will ruin the string data. You should only use this function on strings + * that are completely comprised of low ASCII characters. + * + * \param str the string to reverse. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -1122,7 +3183,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strlwr */ @@ -1143,34 +3204,592 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strupr */ extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); +/** + * Search a string for the first instance of a specific byte. + * + * The search ends once it finds the requested byte value, or a null + * terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the first instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); + +/** + * Search a string for the last instance of a specific byte. + * + * The search must go until it finds a null terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the last instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); + +/** + * Search a string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); + +/** + * Search a string, up to n bytes, for the first instance of a specific + * substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string, or `maxlen` bytes have been examined. It is + * possible to use this function on a string without a null terminator. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \param maxlen the maximum number of bytes to search in `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); + +/** + * Search a UTF-8 string for the first instance of a specific substring, + * case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); -extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr); + +/** + * This works exactly like strtok_r() but doesn't require access to a C + * runtime. + * + * Break a string up into a series of tokens. + * + * To start tokenizing a new string, `str` should be the non-NULL address of + * the string to start tokenizing. Future calls to get the next token from the + * same string should specify a NULL. + * + * Note that this function will overwrite pieces of `str` with null chars to + * split it into tokens. This function cannot be used with const/read-only + * strings! + * + * `saveptr` just needs to point to a `char *` that can be overwritten; SDL + * will use this to save tokenizing state between calls. It is initialized if + * `str` is non-NULL, and used to resume tokenizing when `str` is NULL. + * + * \param str the string to tokenize, or NULL to continue tokenizing. + * \param delim the delimiter string that separates tokens. + * \param saveptr pointer to a char *, used for ongoing state. + * \returns A pointer to the next token, or NULL if no tokens remain. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr); + +/** + * Count the number of codepoints in a UTF-8 string. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strlen(). + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \returns The length (in codepoints, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strnlen + * \sa SDL_strlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); + +/** + * Count the number of codepoints in a UTF-8 string, up to n bytes. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strnlen(). + * + * The counting stops at `bytes` bytes (not codepoints!). This seems + * counterintuitive, but makes it easy to express the total size of the + * string's buffer. + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \param bytes The maximum amount of bytes to count. + * \returns The length (in codepoints, excluding the null terminator) of `src` + * but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strlen + * \sa SDL_strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); +/** + * Convert an integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +/** + * Convert an unsigned integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_itoa + * \sa SDL_ultoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); + +/** + * Convert a long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ultoa + * \sa SDL_itoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); + +/** + * Convert an unsigned long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +#ifndef SDL_NOLONGLONG + +/** + * Convert a long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ulltoa + * \sa SDL_itoa + * \sa SDL_ltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); + +/** + * Convert an unsigned long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); +#endif + +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to + * `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +#ifndef SDL_NOLONGLONG + +/** + * Parse a `long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long long`, the result is + * clamped to the minimum and maximum representable `long long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long long`, or 0 if no number could be + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); +#endif + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. The handling of + * scientific and hexadecimal notation is unspecified. + * - Whether or not INF and NAN can be parsed is unspecified. + * - The precision of the result is unspecified. + * + * \param str the null-terminated string to read. Must not be NULL. + * \param endp if not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \returns the parsed `double`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /** @@ -1189,7 +3808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); @@ -1219,7 +3838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); @@ -1247,7 +3866,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); @@ -1287,20 +3906,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + /** * The Unicode REPLACEMENT CHARACTER codepoint. * - * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string - * with encoding errors. + * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they + * encounter a UTF-8 string with encoding errors. * * This tends to render as something like a question mark in most places. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * + * \sa SDL_StepBackUTF8 * \sa SDL_StepUTF8 */ #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD @@ -1346,10 +3984,41 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); +/** + * Decode a UTF-8 string in reverse, one Unicode codepoint at a time. + * + * This will go to the start of the previous Unicode codepoint in the string, + * move `*pstr` to that location and return that codepoint. + * + * If `*pstr` is already at the start of the string), it will not advance + * `*pstr` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameter each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT. + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param start a pointer to the beginning of the UTF-8 string. + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \returns the previous Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr); + /** * Convert a single Unicode codepoint to UTF-8. * @@ -1375,18 +4044,200 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); - +/** + * This works exactly like sscanf() but doesn't require access to a C runtime. + * + * Scan a string, matching a format string, converting each '%' item and + * storing it to pointers provided through variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); + +/** + * This works exactly like vsscanf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_sscanf(), except it takes a `va_list` instead + * of using `...` variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` of pointers to values to be filled in with scanned + * items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like snprintf() but doesn't require access to a C + * runtime. + * + * Format a string of up to `maxlen`-1 bytes, converting each '%' item with + * values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * bytes will be written at all. + * + * This function returns the number of _bytes_ (not _characters_) that should + * be written, excluding the null-terminator character. If this returns a + * number >= `maxlen`, it means the output string was truncated. A negative + * return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * This works exactly like swprintf() but doesn't require access to a C + * runtime. + * + * Format a wide string of up to `maxlen`-1 wchar_t values, converting each + * '%' item with values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide + * characters will be written at all. + * + * This function returns the number of _wide characters_ (not _codepoints_) + * that should be written, excluding the null-terminator character. If this + * returns a number >= `maxlen`, it means the output string was truncated. A + * negative return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the wide string into. Must not be NULL. + * \param maxlen the maximum wchar_t values to write, including the + * null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like vsnprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); + +/** + * This works exactly like vswprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_swprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum wide characters to write, including the + * null-terminator. + * \param fmt a printf-style format wide string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like asprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it allocates a buffer large + * enough to hold the output string on behalf of the caller. + * + * On success, this function returns the number of bytes (not characters) + * comprising the output string, not counting the null-terminator character, + * and sets `*strp` to the newly-allocated string. + * + * On error, this function returns a negative number, and the value of `*strp` + * is undefined. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * This works exactly like vasprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_asprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** @@ -1401,7 +4252,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR * \threadsafety This should be called on the same thread that calls * SDL_rand*() * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits @@ -1436,7 +4287,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_randf @@ -1459,7 +4310,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_rand @@ -1481,7 +4332,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf(void); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_randf @@ -1516,7 +4367,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits_r @@ -1543,7 +4394,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_bits_r * \sa SDL_rand_r @@ -1569,18 +4420,34 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_r * \sa SDL_randf_r */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); - #ifndef SDL_PI_D + +/** + * The value of Pi, as a double-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_F + */ #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ #endif + #ifndef SDL_PI_F + +/** + * The value of Pi, as a single-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_D + */ #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ #endif @@ -1606,7 +4473,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acosf * \sa SDL_asin @@ -1636,7 +4503,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acos * \sa SDL_asinf @@ -1666,7 +4533,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asinf * \sa SDL_acos @@ -1696,7 +4563,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asin * \sa SDL_acosf @@ -1728,7 +4595,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atanf * \sa SDL_atan2 @@ -1760,7 +4627,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan * \sa SDL_atan2f @@ -1796,7 +4663,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1832,7 +4699,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1858,7 +4725,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceilf * \sa SDL_floor @@ -1886,7 +4753,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceil * \sa SDL_floorf @@ -1915,7 +4782,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabs @@ -1941,7 +4808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabsf @@ -1968,7 +4835,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cosf * \sa SDL_acos @@ -1996,7 +4863,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cos * \sa SDL_acosf @@ -2029,7 +4896,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_expf * \sa SDL_log @@ -2061,7 +4928,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_exp * \sa SDL_logf @@ -2083,7 +4950,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabsf */ @@ -2104,7 +4971,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabs */ @@ -2128,7 +4995,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floorf * \sa SDL_ceil @@ -2156,7 +5023,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floor * \sa SDL_ceilf @@ -2184,7 +5051,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_truncf * \sa SDL_fmod @@ -2213,7 +5080,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_trunc * \sa SDL_fmodf @@ -2242,7 +5109,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmodf * \sa SDL_modf @@ -2272,7 +5139,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmod * \sa SDL_truncf @@ -2292,7 +5159,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinff */ @@ -2306,7 +5173,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinf */ @@ -2320,7 +5187,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnanf */ @@ -2334,7 +5201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnan */ @@ -2362,7 +5229,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_logf * \sa SDL_log10 @@ -2392,7 +5259,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log * \sa SDL_expf @@ -2421,7 +5288,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10f * \sa SDL_log @@ -2451,7 +5318,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10 * \sa SDL_logf @@ -2471,7 +5338,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modff * \sa SDL_trunc @@ -2491,7 +5358,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modf * \sa SDL_truncf @@ -2523,7 +5390,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_powf * \sa SDL_exp @@ -2555,7 +5422,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_pow * \sa SDL_expf @@ -2582,7 +5449,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_roundf * \sa SDL_lround @@ -2611,7 +5478,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_round * \sa SDL_lroundf @@ -2640,7 +5507,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lroundf * \sa SDL_round @@ -2669,7 +5536,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lround * \sa SDL_roundf @@ -2697,7 +5564,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbnf * \sa SDL_pow @@ -2722,7 +5589,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbn * \sa SDL_powf @@ -2749,7 +5616,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sinf * \sa SDL_asin @@ -2765,7 +5632,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * Range: `-1 <= y <= 1` * * This function operates on single-precision floating point values, use - * SDL_sinf for double-precision floats. + * SDL_sin for double-precision floats. * * This function may use a different approximation across different versions, * platforms and configurations. i.e, it can return a different value given @@ -2777,7 +5644,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sin * \sa SDL_asinf @@ -2805,7 +5672,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrtf */ @@ -2831,7 +5698,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrt */ @@ -2857,7 +5724,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tanf * \sa SDL_sin @@ -2887,7 +5754,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tan * \sa SDL_sinf @@ -2897,12 +5764,13 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); */ extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); -/* The SDL implementation of iconv() returns these error codes */ -#define SDL_ICONV_ERROR (size_t)-1 -#define SDL_ICONV_E2BIG (size_t)-2 -#define SDL_ICONV_EILSEQ (size_t)-3 -#define SDL_ICONV_EINVAL (size_t)-4 - +/** + * An opaque handle representing string encoding conversion state. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + */ typedef struct SDL_iconv_data_t *SDL_iconv_t; /** @@ -2914,7 +5782,7 @@ typedef struct SDL_iconv_data_t *SDL_iconv_t; * \returns a handle that must be freed with SDL_iconv_close, or * SDL_ICONV_ERROR on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_close @@ -2929,7 +5797,7 @@ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, * \param cd The character set conversion handle. * \returns 0 on success, or -1 on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_open @@ -2941,7 +5809,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * This function converts text between encodings, reading from and writing to * a buffer. * - * It returns the number of succesful conversions. + * It returns the number of succesful conversions on success. On error, + * SDL_ICONV_E2BIG is returned when the output buffer is too small, or + * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, + * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte sequence. On + * error, this is the location of the problematic input sequence. On + * success, this is the end of the input sequence. + * - inbytesleft will be set to the number of bytes left to convert, which + * will be 0 on success. + * - outbuf will point to the location where to store the next output byte. + * - outbytesleft will be set to the number of bytes left in the output + * buffer. * * \param cd The character set conversion context, created in * SDL_iconv_open(). @@ -2950,23 +5833,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * \param inbytesleft The number of bytes in the input buffer. * \param outbuf Address of variable that points to the output buffer. * \param outbytesleft The number of bytes in the output buffer. - * \returns the number of conversions on success, else SDL_ICONV_E2BIG is - * returned when the output buffer is too small, or SDL_ICONV_EILSEQ - * is returned when an invalid input sequence is encountered, or - * SDL_ICONV_EINVAL is returned when an incomplete input sequence is - * encountered. + * \returns the number of conversions on success, or a negative error code. * - * On exit: - * - * - inbuf will point to the beginning of the next multibyte - * sequence. On error, this is the location of the problematic - * input sequence. On success, this is the end of the input - * sequence. - inbytesleft will be set to the number of bytes left - * to convert, which will be 0 on success. - outbuf will point to - * the location where to store the next output byte. - outbytesleft - * will be set to the number of bytes left in the output buffer. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -2976,6 +5845,12 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); +#define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */ +#define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */ +#define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */ +#define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */ + + /** * Helper function to convert a string's encoding in one call. * @@ -2995,7 +5870,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, * \param inbytesleft the size of the input string _in bytes_. * \returns a new string, converted to the new encoding, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -3006,12 +5881,65 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *inbuf, size_t inbytesleft); -/* Some helper macros for common cases... */ +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) + /* force builds using Clang's static analysis tools to use literal C runtime here, since there are possibly tests that are ineffective otherwise. */ #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) @@ -3034,6 +5962,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include @@ -3073,6 +6004,7 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #define SDL_wcsncmp wcsncmp #define SDL_strcasecmp strcasecmp #define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk #define SDL_sscanf sscanf #define SDL_vsscanf vsscanf #define SDL_snprintf snprintf @@ -3082,29 +6014,27 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); /** * Multiply two integers, checking for overflow. * - * If `a * b` would overflow, return -1. + * If `a * b` would overflow, return false. * - * Otherwise store `a * b` via ret and return 0. + * Otherwise store `a * b` via ret and return true. * * \param a the multiplicand. * \param b the multiplier. - * \param ret on non-overflow output, stores the multiplication result. May + * \param ret on non-overflow output, stores the multiplication result, may * not be NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is multiplied without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) { if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; + return false; } *ret = a * b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION @@ -3112,60 +6042,72 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, /* This needs to be wrapped in an inline rather than being a direct #define, * because __builtin_mul_overflow() is type-generic, but we want to be * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_mul_overflow(a, b, ret) == 0); } -#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) #endif #endif /** * Add two integers, checking for overflow. * - * If `a + b` would overflow, return -1. + * If `a + b` would overflow, return false. * - * Otherwise store `a + b` via ret and return 0. + * Otherwise store `a + b` via ret and return true. * * \param a the first addend. * \param b the second addend. - * \param ret on non-overflow output, stores the addition result. May not be + * \param ret on non-overflow output, stores the addition result, may not be * NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is added without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) { if (b > SDL_SIZE_MAX - a) { - return -1; + return false; } *ret = a + b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION #if SDL_HAS_BUILTIN(__builtin_add_overflow) /* This needs to be wrapped in an inline rather than being a direct #define, * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_add_overflow(a, b, ret) == 0); } -#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) #endif #endif /* This is a generic function pointer which should be cast to the type you expect */ -#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) typedef void *SDL_FunctionPointer; #else typedef void (*SDL_FunctionPointer)(void); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_storage.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_storage.h index 91a90bc..8b89ace 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_storage.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_storage.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,222 @@ /** * # CategoryStorage * - * SDL storage container management. + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) { + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(data); + * } + * } + * } + * + * void ReadSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * + * void WriteSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(NULL, 0); + * if (title == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(title)) { + * SDL_Delay(1); + * } + * + * for (size_t i = 0; i < numFiles; i += 1) { + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) { + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * } + * + * SDL_CloseStorage(title); + * } + * + * void ReadSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) { + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * + * void WriteSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. */ #ifndef SDL_storage_h_ @@ -40,8 +255,6 @@ extern "C" { #endif -/* !!! FIXME: Don't let this ship without async R/W support!!! */ - /** * Function interface for SDL_Storage. * @@ -52,44 +265,61 @@ extern "C" { * It is not usually necessary to do this; SDL provides standard * implementations for many things you might expect to do with an SDL_Storage. * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_StorageInterface { + /* The version of this interface */ + Uint32 version; + /* Called when the storage is closed */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); /* Optional, returns whether the storage is currently ready for access */ - SDL_bool (SDLCALL *ready)(void *userdata); + bool (SDLCALL *ready)(void *userdata); /* Enumerate a directory, optional for write-only storage */ - SDL_bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); /* Get path information, optional for write-only storage */ - SDL_bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); /* Read a file from storage, optional for write-only storage */ - SDL_bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); /* Write a file to storage, optional for read-only storage */ - SDL_bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); /* Create a directory, optional for read-only storage */ - SDL_bool (SDLCALL *mkdir)(void *userdata, const char *path); + bool (SDLCALL *mkdir)(void *userdata, const char *path); /* Remove a file or empty directory, optional for read-only storage */ - SDL_bool (SDLCALL *remove)(void *userdata, const char *path); + bool (SDLCALL *remove)(void *userdata, const char *path); /* Rename a path, optional for read-only storage */ - SDL_bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); /* Copy a file, optional for read-only storage */ - SDL_bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); } SDL_StorageInterface; +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + /** * An abstract interface for filesystem access. * @@ -97,7 +327,7 @@ typedef struct SDL_StorageInterface * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create * an object with a custom implementation using SDL_OpenStorage. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Storage SDL_Storage; @@ -109,7 +339,7 @@ typedef struct SDL_Storage SDL_Storage; * \returns a title storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -132,7 +362,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *overr * \returns a user storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -156,7 +386,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, c * \returns a filesystem storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -176,16 +406,21 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * or SDL_OpenUserStorage(). * - * \param iface the function table to be used by this container. - * \param userdata the pointer that will be passed to the store interface. + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE * \sa SDL_ReadStorageFile * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -196,33 +431,33 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * Closes and frees a storage container. * * \param storage a storage container to close. - * \returns SDL_TRUE if the container was freed with no errors, SDL_FALSE - * otherwise; call SDL_GetError() for more information. Even if the - * function returns an error, the container data will be freed; the - * error is only for informational purposes. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenFileStorage * \sa SDL_OpenStorage * \sa SDL_OpenTitleStorage * \sa SDL_OpenUserStorage */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); /** * Checks if the storage container is ready to use. * - * This function should be called in regular intervals until it returns - * SDL_TRUE - however, it is not recommended to spinwait on this call, as the - * backend may depend on a synchronous message loop. + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. * * \param storage a storage container to query. - * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise. + * \returns true if the container is ready, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); /** * Query the size of a file within a storage container. @@ -230,34 +465,38 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); * \param storage a storage container to query. * \param path the relative path of the file to query. * \param length a pointer to be filled with the file's length. - * \returns SDL_TRUE if the file could be queried or SDL_FALSE on failure; - * call SDL_GetError() for more information. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); /** * Synchronously read a file from a storage container into a client-provided * buffer. * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * * \param storage a storage container to read from. * \param path the relative path of the file to read. * \param destination a client-provided buffer to read the file into. * \param length the length of the destination buffer. - * \returns SDL_TRUE if the file was read or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageFileSize * \sa SDL_StorageReady * \sa SDL_WriteStorageFile */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); /** * Synchronously write a file from client memory into a storage container. @@ -266,64 +505,73 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, c * \param path the relative path of the file to write. * \param source a client-provided buffer to write from. * \param length the length of the source buffer. - * \returns SDL_TRUE if the file was written or SDL_FALSE on failure; call + * \returns true if the file was written or false on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageSpaceRemaining * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); /** * Create a directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); /** * Enumerate a directory in a storage container through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); /** * Rename a file or directory in a writable storage container. @@ -331,14 +579,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Copy a file in a writable storage container. @@ -346,14 +594,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Get information about a filesystem path in a storage container. @@ -362,14 +610,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, c * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); /** * Queries the remaining space in a storage container. @@ -377,7 +625,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage * \param storage a storage container to query. * \returns the amount of remaining space, in bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -401,8 +649,11 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param pattern the pattern that files in the directory must match. Can be * NULL. * \param flags `SDL_GLOB_*` bitflags that affect this search. @@ -417,7 +668,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * \threadsafety It is safe to call this function from any thread, assuming * the `storage` object is thread-safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_surface.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_surface.h index aafe574..0752f53 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_surface.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_surface.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,19 @@ /** * # CategorySurface * - * SDL_Surface definition and management functions. + * SDL surfaces are buffers of pixels in system RAM. These are useful for + * passing around and manipulating images that are not stored in GPU memory. + * + * SDL_Surface makes serious efforts to manage images in various formats, and + * provides a reasonable toolbox for transforming the data, including copying + * between surfaces, filling rectangles in the image data, etc. + * + * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not + * provide loaders for various other file formats, but there are several + * excellent external libraries that do, including its own satellite library, + * SDL_image: + * + * https://github.com/libsdl-org/SDL_image */ #ifndef SDL_surface_h_ @@ -47,7 +59,7 @@ extern "C" { * * These are generally considered read-only. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SurfaceFlags; @@ -59,14 +71,14 @@ typedef Uint32 SDL_SurfaceFlags; /** * Evaluates to true if the surface needs to be locked before access. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MUSTLOCK(S) ((((S)->flags & SDL_SURFACE_LOCK_NEEDED)) == SDL_SURFACE_LOCK_NEEDED) /** * The scaling mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ScaleMode { @@ -77,7 +89,7 @@ typedef enum SDL_ScaleMode /** * The flip mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlipMode { @@ -86,8 +98,7 @@ typedef enum SDL_FlipMode SDL_FLIP_VERTICAL /**< flip vertically */ } SDL_FlipMode; -/* Internal surface data */ -typedef struct SDL_SurfaceData SDL_SurfaceData; +#ifndef SDL_INTERNAL /** * A collection of pixels used in software blitting. @@ -104,22 +115,32 @@ typedef struct SDL_SurfaceData SDL_SurfaceData; * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * - * \since This struct is available since SDL 3.0.0. + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface */ -typedef struct SDL_Surface +struct SDL_Surface { - SDL_SurfaceFlags flags; /**< Read-only */ - SDL_PixelFormat format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-only pointer, writable pixels if non-NULL */ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ int refcount; /**< Application reference count, used when freeing surface */ - SDL_SurfaceData *internal; /**< Private */ - -} SDL_Surface; + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ +typedef struct SDL_Surface SDL_Surface; /** * Allocate a new surface with a specific pixel format. @@ -132,7 +153,7 @@ typedef struct SDL_Surface * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurfaceFrom * \sa SDL_DestroySurface @@ -160,7 +181,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurface(int width, int heigh * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -174,9 +195,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurfaceFrom(int width, int h * * \param surface the SDL_Surface to free. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_CreateStackSurface * \sa SDL_CreateSurface * \sa SDL_CreateSurfaceFrom */ @@ -206,7 +226,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface); @@ -221,16 +241,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac * interpreted in color operations. * * \param surface the SDL_Surface structure to update. - * \param colorspace an SDL_ColorSpace value describing the surface + * \param colorspace an SDL_Colorspace value describing the surface * colorspace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); /** * Get the colorspace used by a surface. @@ -243,7 +263,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surfa * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if * the surface is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorspace */ @@ -271,7 +291,7 @@ extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface * the surface didn't have an index format); call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -284,15 +304,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface * * * \param surface the SDL_Surface structure to update. * \param palette the SDL_Palette structure to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); /** * Get the palette used by a surface. @@ -301,7 +321,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, * \returns a pointer to the palette used by the surface, or NULL if there is * no palette used. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfacePalette */ @@ -321,31 +341,30 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \param surface the SDL_Surface structure to update. * \param image a pointer to an alternate SDL_Surface to associate with this * surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages * \sa SDL_SurfaceHasAlternateImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); /** * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true if alternate versions are available or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); /** * Get an array including all versions of a surface. @@ -364,7 +383,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface * * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -380,7 +399,7 @@ extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *sur * * \param surface the SDL_Surface structure to update. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_GetSurfaceImages @@ -401,22 +420,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s * format of the surface will not change. * * \param surface the SDL_Surface structure to be locked. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockSurface(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); /** * Release a surface after directly accessing the pixels. * * \param surface the SDL_Surface structure to be unlocked. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSurface */ @@ -429,18 +448,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * will result in a memory leak. * * \param src the data stream for the surface. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); /** * Load a BMP image from a file. @@ -452,7 +471,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP_IO @@ -471,17 +490,17 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); * * \param surface the SDL_Surface structure containing the image to be saved. * \param dst a data stream to save to. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, - * even in the case of an error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closeio if true, calls SDL_CloseIO() on `dst` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, SDL_bool closeio); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); /** * Save a surface to a file. @@ -494,15 +513,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IO * * \param surface the SDL_Surface structure containing the image to be saved. * \param file a file to save to. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); /** * Set the RLE acceleration hint for a surface. @@ -511,32 +530,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const cha * the surface must be locked before directly accessing the pixels. * * \param surface the SDL_Surface structure to optimize. - * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable - * it. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable RLE acceleration, false to disable it. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface * \sa SDL_LockSurface * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); /** * Returns whether the surface is RLE enabled. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. + * \returns true if the surface is RLE enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceRLE */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); /** * Set the color key (transparent pixel) in a surface. @@ -549,34 +567,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * SDL_MapRGB(). * * \param surface the SDL_Surface structure to update. - * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color - * key. + * \param enabled true to enable color key, false to disable color key. * \param key the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorKey * \sa SDL_SetSurfaceRLE * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); /** * Returns whether the surface has a color key. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. + * \returns true if the surface has a color key, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); /** * Get the color key (transparent pixel) for a surface. @@ -584,19 +601,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface * The color key is a pixel of the format used by the surface, as generated by * SDL_MapRGB(). * - * If the surface doesn't have color key enabled this function returns -1. + * If the surface doesn't have color key enabled this function returns false. * * \param surface the SDL_Surface structure to query. * \param key a pointer filled in with the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); /** * Set an additional color value multiplied into blit operations. @@ -611,15 +628,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface * \param r the red color value multiplied into blit operations. * \param g the green color value multiplied into blit operations. * \param b the blue color value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); /** @@ -629,15 +646,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); /** * Set an additional alpha value used in blit operations. @@ -649,30 +666,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param alpha the alpha value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); /** * Get the additional alpha value used in blit operations. * * \param surface the SDL_Surface structure to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); /** * Set the blend mode used for blit operations. @@ -683,28 +700,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); /** * Get the blend mode used for blit operations. * * \param surface the SDL_Surface structure to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); /** * Set the clipping rectangle for a surface. @@ -718,14 +735,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surfac * \param surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); /** * Get the clipping rectangle for a surface. @@ -737,26 +754,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for * the surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); /** * Flip a surface vertically or horizontally. * * \param surface the surface to flip. * \param flip the direction to flip. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); /** * Creates a new surface identical to the existing surface. @@ -770,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_F * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -789,7 +806,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surf * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -814,7 +831,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface, * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurfaceAndColorspace * \sa SDL_DestroySurface @@ -840,10 +857,9 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurface - * \sa SDL_ConvertSurface * \sa SDL_DestroySurface */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props); @@ -859,14 +875,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Su * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixelsAndColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); /** * Copy a block of pixels of one format and colorspace to another format and @@ -875,27 +891,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SD * \param width the width of the block to copy, in pixels. * \param height the height of the block to copy, in pixels. * \param src_format an SDL_PixelFormat value of the `src` pixels format. - * \param src_colorspace an SDL_ColorSpace value describing the colorspace of + * \param src_colorspace an SDL_Colorspace value describing the colorspace of * the `src` pixels. * \param src_properties an SDL_PropertiesID with additional source color * properties, or 0. * \param src a pointer to the source pixels. * \param src_pitch the pitch of the source pixels, in bytes. * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. - * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of * the `dst` pixels. * \param dst_properties an SDL_PropertiesID with additional destination color * properties, or 0. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixels */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); /** * Premultiply the alpha on a block of pixels. @@ -910,14 +926,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, i * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with premultiplied pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); /** * Premultiply the alpha in a surface. @@ -925,14 +941,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, * This is safe to use with src == dst, but not for other overlapping areas. * * \param surface the surface to modify. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); /** * Clear a surface with a specific color, with floating point precision. @@ -947,12 +963,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *su * \param g the green component of the pixel, normally in the range 0-1. * \param b the blue component of the pixel, normally in the range 0-1. * \param a the alpha component of the pixel, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); /** * Perform a fast fill of a rectangle with a specific color. @@ -970,14 +986,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, floa * \param rect the SDL_Rect structure representing the rectangle to fill, or * NULL to fill the entire surface. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); /** * Perform a fast fill of a set of rectangles with a specific color. @@ -995,22 +1011,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const * \param rects an array of SDL_Rects representing the rectangles to fill. * \param count the number of rectangles in the array. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); /** - * Performs a fast blit from the source surface to the destination surface. + * Performs a fast blit from the source surface to the destination surface + * with clipping. * - * This assumes that the source and destination rectangles are the same size. * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or - * `dst`) is copied. The final blit rectangles are saved in `srcrect` and - * `dstrect` after all clipping is performed. + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. + * + * The final blit rectangles are saved in `srcrect` and `dstrect` after all + * clipping is performed. * * The blit function should not be called on a locked surface. * @@ -1066,18 +1084,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, cons * height are ignored, and are copied from `srcrect`. If you * want a specific width and height, you should use * SDL_BlitSurfaceScaled(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform low-level surface blitting only. @@ -1091,18 +1109,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit to a destination surface, which may be of a different @@ -1116,18 +1134,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, * the destination surface, or NULL to fill the entire * destination surface. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform low-level surface scaled blitting only. @@ -1142,18 +1160,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, con * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform a tiled blit to a destination surface, which may be of a different @@ -1168,18 +1186,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled and tiled blit to a destination surface, which may be of a @@ -1198,18 +1216,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, cons * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit using the 9-grid algorithm to a destination surface, @@ -1235,18 +1253,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface * * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Map an RGB triple to an opaque pixel value for a surface. @@ -1272,7 +1290,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, cons * \param b the blue component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGBA */ @@ -1303,7 +1321,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 * \param a the alpha component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGB */ @@ -1329,12 +1347,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint * ignore this channel. * \param a a pointer filled in with the alpha channel, 0-255, or NULL to * ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Retrieves a single pixel from a surface. @@ -1353,12 +1371,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, * 0-1, or NULL to ignore this channel. * \param a a pointer filled in with the alpha channel, normally in the range * 0-1, or NULL to ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); /** * Writes a single pixel to a surface. @@ -1376,12 +1394,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surf * \param g the green channel value, 0-255. * \param b the blue channel value, 0-255. * \param a the alpha channel value, 0-255. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Writes a single pixel to a surface. @@ -1396,12 +1414,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, * \param g the green channel value, normally in the range 0-1. * \param b the blue channel value, normally in the range 0-1. * \param a the alpha channel value, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_system.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_system.h index 17ac0a1..294089f 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_system.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_system.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,13 @@ /** * # CategorySystem * - * Platform-specific SDL API functions. + * Platform-specific SDL API functions. These are functions that deal with + * needs of specific operating systems, that didn't make sense to offer as + * platform-independent, generic APIs. + * + * Most apps can make do without these functions, but they can be useful for + * integrating with other parts of a specific system, adding platform-specific + * polish to an app, or solving problems that only affect one target. */ #ifndef SDL_system_h_ @@ -31,7 +37,6 @@ #include #include #include -#include #include #include @@ -44,16 +49,15 @@ extern "C" { /* * Platform specific functions for Windows */ -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) typedef struct tagMSG MSG; /** * A callback to be used with SDL_SetWindowsMessageHook. * - * This callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * This callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * As this is processing a message directly from the Windows event loop, this * callback should do the minimum required work and return quickly. @@ -61,36 +65,35 @@ typedef struct tagMSG MSG; * \param userdata the app-defined pointer provided to * SDL_SetWindowsMessageHook. * \param msg a pointer to a Win32 event structure to process. - * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it. + * \returns true to let event continue on, false to drop it. * * \threadsafety This may only be called (by SDL) from the thread handling the * Windows event loop. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetWindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ -typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); /** * Set a callback for every Windows message, run before TranslateMessage(). * - * The callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_WindowsMessageHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) @@ -104,14 +107,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo * \returns the D3D9 adapter index on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ - -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) - /** * Get the DXGI Adapter and Output indices for the specified display. * @@ -122,33 +121,55 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displ * \param displayID the instance of the display to query. * \param adapterIndex a pointer to be filled in with the adapter index. * \param outputIndex a pointer to be filled in with the output index. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + /* * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _XEvent XEvent; -typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); + +/** + * A callback to be used with SDL_SetX11EventHook. + * + * This callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * As this is processing an event directly from the X11 event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to SDL_SetX11EventHook. + * \param xevent a pointer to an Xlib XEvent union to process. + * \returns true to let event continue on, false to drop it. + * + * \threadsafety This may only be called (by SDL) from the thread handling the + * X11 event loop. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetX11EventHook + */ +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** * Set a callback for every X11 event. * - * The callback may modify the event, and should return SDL_TRUE if the event - * should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_X11EventHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); @@ -162,12 +183,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, * * \param threadID the Unix thread ID to change priority of. * \param priority the new, Unix-specific, priority value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); /** * Sets the priority (not nice level) and scheduling policy for a thread. @@ -178,12 +199,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, * \param sdlPriority the new SDL_ThreadPriority value. * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, * SCHED_OTHER, etc...). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); #endif /* SDL_PLATFORM_LINUX */ @@ -204,7 +225,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 * \param userdata what was passed as `callbackParam` to * SDL_SetiOSAnimationCallback as `callbackParam`. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ @@ -240,27 +261,27 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSEventPump */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); /** * Use this function to enable or disable the SDL event pump on Apple iOS. * * This function is only available on Apple iOS. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. + * \param enabled true to enable the event pump, false to disable it. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); #endif /* SDL_PLATFORM_IOS */ @@ -286,7 +307,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidActivity */ @@ -311,7 +332,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidJNIEnv */ @@ -349,43 +370,34 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); * * \returns the Android API level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - /** * Query if the application is running on a Chromebook. * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * \returns true if this is a Chromebook, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); /** * Query if the application is running on a Samsung DeX docking station. * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * \returns true if this is a DeX docking station, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); /** * Trigger the Android system back button behavior. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); @@ -393,9 +405,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * See the official Android developer guide for more information: * http://developer.android.com/guide/topics/data/data-storage.html * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 + +/** + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -414,9 +433,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \returns the path used for internal storage or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidExternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void); @@ -431,7 +451,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void) * \returns the current state of external storage, or 0 if external storage is * currently unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStoragePath */ @@ -453,9 +473,11 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); * \returns the path used for external storage for this application on success * or NULL on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void); @@ -474,12 +496,25 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) * \returns the path used for caches for this application on success or NULL * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidExternalStoragePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - -typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted); +/** + * Callback that presents a response from a SDL_RequestAndroidPermission call. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param permission the Android-specific permission name that was requested. + * \param granted true if permission is granted, false if denied. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RequestAndroidPermission + */ +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** * Request permissions at runtime, asynchronously. @@ -500,18 +535,22 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * like memory running out. Normally there will be a yes or no to the request * through the callback. * + * For the `permission` parameter, choose a value from here: + * + * https://developer.android.com/reference/android/Manifest.permission + * * \param permission the permission to request. * \param cb the callback to trigger when the request has a response. * \param userdata an app-controlled pointer that is passed to the callback. - * \returns SDL_TRUE if the request was submitted, SDL_FALSE if there was an - * error submitting. The result of the request is only ever reported + * \returns true if the request was submitted, false if there was an error + * submitting. The result of the request is only ever reported * through the callback, not this return value. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); /** * Shows an Android toast notification. @@ -532,14 +571,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *pe * \param gravity where the notification should appear on the screen. * \param xoffset set this parameter only when gravity >=0. * \param yoffset set this parameter only when gravity >=0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); /** * Send a user command to SDLActivity. @@ -548,111 +587,63 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, i * * \param command user command that must be greater or equal to 0x8000. * \param param user parameter. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); #endif /* SDL_PLATFORM_ANDROID */ -/* - * Platform specific functions for WinRT - */ -#ifdef SDL_PLATFORM_WINRT - -/** - * WinRT / Windows Phone path types - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_Path -{ - /** The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily(); - -#endif /* SDL_PLATFORM_WINRT */ - /** * Query if the current device is a tablet. * - * If SDL can't determine this, it will return SDL_FALSE. + * If SDL can't determine this, it will return false. * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * \returns true if the device is a tablet, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_Sandbox +{ + SDL_SANDBOX_NONE = 0, + SDL_SANDBOX_UNKNOWN_CONTAINER, + SDL_SANDBOX_FLATPAK, + SDL_SANDBOX_SNAP, + SDL_SANDBOX_MACOS +} SDL_Sandbox; + +/** + * Get the application sandbox environment, if any. + * + * \returns the application sandbox environment or SDL_SANDBOX_NONE if the + * application is not running in a sandbox environment. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void); + /* Functions used by iOS app delegates to notify SDL about state changes. */ @@ -669,7 +660,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); @@ -686,7 +677,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); @@ -703,7 +694,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); @@ -720,7 +711,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); @@ -737,7 +728,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); @@ -754,7 +745,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); @@ -773,7 +764,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); #endif @@ -794,12 +785,12 @@ typedef struct XUser *XUserHandle; * leak. * * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); /** * Gets a reference to the default user handle for GDK. @@ -809,12 +800,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTa * * \param outUserHandle a pointer to be filled in with the default user * handle. - * \returns SDL_TRUE if success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); #endif diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_thread.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_thread.h index 0fdc8a0..277535f 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_thread.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_thread.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,19 @@ /** * # CategoryThread * - * SDL thread management routines. + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. */ #include @@ -34,9 +46,8 @@ /* Thread synchronization primitives */ #include -#include -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +#if defined(SDL_PLATFORM_WINDOWS) #include /* _beginthreadex() and _endthreadex() */ #endif @@ -51,7 +62,7 @@ extern "C" { * * These are opaque data. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -65,7 +76,7 @@ typedef struct SDL_Thread SDL_Thread; * application will operate on, but having a way to uniquely identify a thread * can be useful at times. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetThreadID * \sa SDL_GetCurrentThreadID @@ -78,7 +89,7 @@ typedef Uint64 SDL_ThreadID; * 0 is the invalid ID. An app can create these and then set data for these * IDs that is unique to each thread. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetTLS * \sa SDL_SetTLS @@ -90,11 +101,11 @@ typedef SDL_AtomicInt SDL_TLSID; * * SDL will make system changes as necessary in order to apply the thread * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, @@ -103,13 +114,30 @@ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_TIME_CRITICAL } SDL_ThreadPriority; +/** + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + */ +typedef enum SDL_ThreadState +{ + SDL_THREAD_UNKNOWN, /**< The thread is not valid */ + SDL_THREAD_ALIVE, /**< The thread is currently running */ + SDL_THREAD_DETACHED, /**< The thread is detached and can't be waited on */ + SDL_THREAD_COMPLETE /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} SDL_ThreadState; + /** * The function passed to SDL_CreateThread() as the new thread's entry point. * * \param data what was passed as `data` to SDL_CreateThread(). * \returns a value that can be reported through SDL_WaitThread(). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -179,7 +207,7 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThreadWithProperties * \sa SDL_WaitThread @@ -245,7 +273,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -263,7 +291,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop /* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ #ifndef SDL_WIKI_DOCUMENTATION_SECTION -# if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +# if defined(SDL_PLATFORM_WINDOWS) # ifndef SDL_BeginThreadFunction # define SDL_BeginThreadFunction _beginthreadex # endif @@ -300,7 +328,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -314,7 +342,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunct * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -334,7 +362,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S * \returns a pointer to a UTF-8 string that names the specified thread, or * NULL if it doesn't have a name. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); @@ -350,7 +378,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); * * \returns the ID of the current thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetThreadID */ @@ -367,7 +395,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentThreadID */ @@ -381,25 +409,25 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * an administrator account. Be prepared for this to fail. * * \param priority the SDL_ThreadPriority to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); /** * Wait for a thread to finish. * - * Threads that haven't been detached will remain (as a "zombie") until this - * function cleans them up. Not doing so is a resource leak. + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. * * Once a thread has been cleaned up through this function, the SDL_Thread * that references it becomes invalid and should not be referenced again. As * such, only one thread may call SDL_WaitThread() on another. * - * The return code for the thread function is placed in the area pointed to by - * `status`, if `status` is not NULL. + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. * * You may not wait on a thread that has been used in a call to * SDL_DetachThread(). Use either that function or this one, but not both, or @@ -412,17 +440,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority pr * * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. - * \param status pointer to an integer that will receive the value returned - * from the thread function by its 'return', or NULL to not - * receive such value back. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_DetachThread */ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status); +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *thread); + /** * Let a thread clean up on exit without intervention. * @@ -452,7 +493,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status) * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -468,7 +509,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread *thread); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -481,7 +522,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetTLS(SDL_TLSID *id); * * \param value a pointer previously handed to SDL_SetTLS. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -504,16 +545,16 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * \param value the value to associate with the ID for the current thread. * \param destructor a function called when the thread exits, to free the * value, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTLS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. @@ -524,7 +565,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CleanupTLS(void); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_time.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_time.h index 86c1fad..b6d3f6d 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_time.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_time.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ freely, subject to the following restrictions: * # CategoryTime * * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. */ #include @@ -41,7 +49,7 @@ extern "C" { * A structure holding a calendar date and time broken down into its * components. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DateTime { @@ -59,7 +67,7 @@ typedef struct SDL_DateTime /** * The preferred date format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -73,7 +81,7 @@ typedef enum SDL_DateFormat /** * The preferred time format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -95,24 +103,24 @@ typedef enum SDL_TimeFormat * format, may be NULL. * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * format, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); /** * Gets the current value of the system realtime clock in nanoseconds since * Jan 1, 1970 in Universal Coordinated Time (UTC). * * \param ticks the SDL_Time to hold the returned tick count. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); /** * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in @@ -123,12 +131,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \param localTime the resulting SDL_DateTime will be expressed in local time * if true, otherwise it will be in Universal Coordinated * Time (UTC). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime); +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); /** * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. @@ -138,12 +146,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_Date * * \param dt the source SDL_DateTime. * \param ticks the resulting SDL_Time. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); /** * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals @@ -157,7 +165,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, * \param dwHighDateTime a pointer filled in with the high portion of the * Windows FILETIME value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); @@ -172,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow * \param dwHighDateTime the high portion of the Windows FILETIME value. * \returns the converted SDL time. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); @@ -184,7 +192,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * \returns the number of days in the requested month or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); @@ -197,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \returns the day of year [0-365] if the date is valid or -1 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); @@ -210,7 +218,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or * -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_timer.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_timer.h index 9d05161..cf94881 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_timer.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_timer.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,20 @@ /** * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. */ #include @@ -38,16 +51,137 @@ extern "C" { #endif /* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_US 1000 + +/** + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND) + +/** + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND) + +/** + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS) + +/** + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS) + +/** + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US) + +/** + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) /** @@ -56,7 +190,9 @@ extern "C" { * \returns an unsigned 64-bit value representing the number of milliseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); @@ -66,7 +202,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); * \returns an unsigned 64-bit value representing the number of nanoseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); @@ -81,7 +219,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); * * \returns the current counter value. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceFrequency */ @@ -92,7 +232,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); * * \returns a platform-specific count per second. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceCounter */ @@ -107,10 +249,33 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * * \param ms the number of milliseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); + /** * Wait a specified number of nanoseconds before returning. * @@ -120,14 +285,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * * \param ns the number of nanoseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS */ -extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); +extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); /** * Definition of the timer ID type. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_TimerID; @@ -151,7 +321,7 @@ typedef Uint32 SDL_TimerID; * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimer */ @@ -160,8 +330,6 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimer() call and should return the next * timer interval. If the value returned from the callback is 0, the timer is @@ -188,7 +356,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimerNS * \sa SDL_RemoveTimer @@ -215,7 +383,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimerNS */ @@ -224,8 +392,6 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimerNS() call and should return the * next timer interval. If the value returned from the callback is 0, the @@ -252,7 +418,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer * \sa SDL_RemoveTimer @@ -263,14 +429,16 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * Remove a timer created with SDL_AddTimer(). * * \param id the ID of the timer to remove. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_touch.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_touch.h index 6889f36..64845a1 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_touch.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_touch.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryTouch * - * SDL touch management. + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. */ #ifndef SDL_touch_h_ @@ -31,7 +42,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -39,25 +49,53 @@ extern "C" { #endif +/** + * A unique ID for a touch device. + * + * This ID is valid for the time the device is connected to the system, and is + * never reused for the lifetime of the application. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_TouchID; + +/** + * A unique ID for a single finger on a touch device. + * + * This ID is valid for the time the finger (stylus, etc) is touching and will + * be unique for all fingers currently in contact, so this ID tracks the + * lifetime of a single continuous touch. This value may represent an index, a + * pointer, or some other unique ID, depending on the platform. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_FingerID; +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_TouchDeviceType { SDL_TOUCH_DEVICE_INVALID = -1, - SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ + SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */ } SDL_TouchDeviceType; /** * Data about a single finger in a multitouch event. * - * Each touch even is a collection of fingers that are simultaneously in + * Each touch event is a collection of fingers that are simultaneously in * contact with the touch device (so a "touch" can be a "multitouch," in * reality), and this struct reports details of the specific fingers. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetTouchFingers */ @@ -69,10 +107,18 @@ typedef struct SDL_Finger float pressure; /**< the quantity of pressure applied, normalized (0...1) */ } SDL_Finger; -/* Used as the device ID for mouse events simulated with touch input */ +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) -/* Used as the SDL_TouchID for touch events simulated with mouse input */ +/** + * The SDL_TouchID for touch events simulated with mouse input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) @@ -89,7 +135,7 @@ typedef struct SDL_Finger * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); @@ -100,7 +146,7 @@ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); * \returns touch device name, or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID); @@ -110,7 +156,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touc * \param touchID the ID of a touch device. * \returns touch device type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); @@ -125,7 +171,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count); diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_tray.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_tray.h new file mode 100644 index 0000000..0b05db2 --- /dev/null +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryTray + * + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. + */ + +#ifndef SDL_tray_h_ +#define SDL_tray_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Tray SDL_Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayMenu SDL_TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayEntry SDL_TrayEntry; + +/** + * Flags that control the creation of system tray entries. + * + * Some of these flags are required; exactly one of them must be specified at + * the time a tray entry is created. Other flags are optional; zero or more of + * those can be OR'ed together with the required flag. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +typedef Uint32 SDL_TrayEntryFlags; + +#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */ +#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */ +#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */ +#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */ +#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */ + +/** + * A callback that is invoked when a tray entry is selected. + * + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param entry the tray entry that was selected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTrayEntryCallback + */ +typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); + +/** + * Create an icon to be placed in the operating system's tray, or equivalent. + * + * Many platforms advise not using a system tray unless persistence is a + * necessary feature. Avoid needlessly creating a tray icon, as the user may + * feel like it clutters their interface. + * + * Using tray icons require the video subsystem. + * + * \param icon a surface to be used as icon. May be NULL. + * \param tooltip a tooltip to be displayed when the mouse hovers the icon in + * UTF-8 encoding. Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenu + * \sa SDL_DestroyTray + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip); + +/** + * Updates the system tray icon's icon. + * + * \param tray the tray icon to be updated. + * \param icon the new icon. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon); + +/** + * Updates the system tray icon's tooltip. + * + * \param tray the tray icon to be updated. + * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip); + +/** + * Create a menu for a system tray. + * + * This should be called at most once per tray icon. + * + * This function does the same thing as SDL_CreateTraySubmenu(), except that + * it takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_GetTrayMenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); + +/** + * Create a submenu for a system tray entry. + * + * This should be called at most once per tray entry. + * + * This function does the same thing as SDL_CreateTrayMenu, except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTraySubmenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry); + +/** + * Gets a previously created tray menu. + * + * You should have called SDL_CreateTrayMenu() on the tray object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTraySubmenu(), except that it + * takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_CreateTrayMenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); + +/** + * Gets a previously created tray entry submenu. + * + * You should have called SDL_CreateTraySubmenu() on the entry object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTrayMenu(), except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_CreateTraySubmenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry); + +/** + * Returns a list of entries in the menu, in order. + * + * \param menu The menu to get entries from. + * \param size An optional pointer to obtain the number of entries in the + * menu. + * \returns a NULL-terminated list of entries within the given menu. The + * pointer becomes invalid when any function that inserts or deletes + * entries in the menu is called. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveTrayEntry + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size); + +/** + * Removes a tray entry. + * + * \param entry The entry to be deleted. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); + +/** + * Insert a tray entry at a given position. + * + * If label is NULL, the entry will be a separator. Many functions won't work + * for an entry that is a separator. + * + * An entry does not need to be destroyed; it will be destroyed with the tray. + * + * \param menu the menu to append the entry to. + * \param pos the desired position for the new entry. Entries at or following + * this place will be moved. If pos is -1, the entry is appended. + * \param label the text to be displayed on the entry, in UTF-8 encoding, or + * NULL for a separator. + * \param flags a combination of flags, some of which are mandatory. + * \returns the newly created entry, or NULL if pos is out of bounds. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TrayEntryFlags + * \sa SDL_GetTrayEntries + * \sa SDL_RemoveTrayEntry + * \sa SDL_GetTrayEntryParent + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags); + +/** + * Sets the label of an entry. + * + * An entry cannot change between a separator and an ordinary entry; that is, + * it is not possible to set a non-NULL label on an entry that has a NULL + * label (separators), or to set a NULL label to an entry that has a non-NULL + * label. The function will silently fail if that happens. + * + * \param entry the entry to be updated. + * \param label the new label for the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryLabel + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label); + +/** + * Gets the label of an entry. + * + * If the returned value is NULL, the entry is a separator. + * + * \param entry the entry to be read. + * \returns the label of the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryLabel + */ +extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be updated. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryChecked + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked); + +/** + * Gets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be read. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryChecked + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is enabled. + * + * \param entry the entry to be updated. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled); + +/** + * Gets whether or not an entry is enabled. + * + * \param entry the entry to be read. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); + +/** + * Sets a callback to be invoked when the entry is selected. + * + * \param entry the entry to be updated. + * \param callback a callback to be invoked when the entry is selected. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata); + +/** + * Simulate a click on a tray entry. + * + * \param entry The entry to activate. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); + +/** + * Gets the menu containing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry); + +/** + * Gets the entry for which the menu is a submenu, if the current menu is a + * submenu. + * + * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent entry. + * \returns the parent entry, or NULL if this menu is not a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTraySubmenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu); + +/** + * Gets the tray for which this menu is the first-level menu, if the current + * menu isn't a submenu. + * + * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent enttrayry. + * \returns the parent tray, or NULL if this menu is a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); + +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_version.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_version.h index c0f518d..55014e3 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_version.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_version.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -30,7 +30,6 @@ #define SDL_version_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -43,7 +42,7 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 3. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MAJOR_VERSION 3 @@ -52,18 +51,18 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 2. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MINOR_VERSION 1 +#define SDL_MINOR_VERSION 2 /** * The current micro (or patchlevel) version of the SDL headers. * * If this were SDL version 3.2.1, this value would be 1. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MICRO_VERSION 2 +#define SDL_MICRO_VERSION 0 /** * This macro turns the version numbers into a numeric value. @@ -74,7 +73,7 @@ extern "C" { * \param minor the minorversion number. * \param patch the patch version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM(major, minor, patch) \ ((major) * 1000000 + (minor) * 1000 + (patch)) @@ -86,7 +85,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) @@ -97,7 +96,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) @@ -108,14 +107,16 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) /** * This is the version number macro for the current SDL version. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion */ #define SDL_VERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION) @@ -123,7 +124,7 @@ extern "C" { /** * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ (SDL_VERSION >= SDL_VERSIONNUM(X, Y, Z)) @@ -140,7 +141,7 @@ extern "C" { * * \returns the version of the linked library. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRevision */ @@ -166,7 +167,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); * \returns an arbitrary string, uniquely identifying the exact revision of * the SDL library in use. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVersion */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_video.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_video.h index 7cce828..a7afc32 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_video.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_video.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,28 @@ /** * # CategoryVideo * - * SDL video functions. + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). */ #ifndef SDL_video_h_ @@ -49,7 +70,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_DisplayID; @@ -58,7 +79,7 @@ typedef Uint32 SDL_DisplayID; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_WindowID; @@ -82,7 +103,7 @@ typedef Uint32 SDL_WindowID; /** * System theme. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemTheme { @@ -91,13 +112,21 @@ typedef enum SDL_SystemTheme SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ } SDL_SystemTheme; -/* Internal display mode data */ +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** * The structure that defines a display mode. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetFullscreenDisplayModes * \sa SDL_GetDesktopDisplayMode @@ -123,7 +152,7 @@ typedef struct SDL_DisplayMode /** * Display orientation values; the way a display is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_DisplayOrientation { @@ -137,7 +166,7 @@ typedef enum SDL_DisplayOrientation /** * The struct used as an opaque handle to a window. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateWindow */ @@ -151,7 +180,7 @@ typedef struct SDL_Window SDL_Window; * changed on existing windows by the app, and some of it might be altered by * the user or system outside of the app's control. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ @@ -185,31 +214,91 @@ typedef Uint64 SDL_WindowFlags; /** - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. * - * \since This macro is available since SDL 3.0.0. + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u + +/** + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) + +/** + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A magic value used with SDL_WINDOWPOS_CENTERED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u /** * Used to indicate that the window position should be centered. * - * \since This macro is available since SDL 3.0.0. + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. */ -#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) + +/** + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlashOperation { @@ -221,30 +310,102 @@ typedef enum SDL_FlashOperation /** * An opaque handle to an OpenGL context. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef int SDL_EGLint; /** - * EGL attribute initialization callback types. + * EGL platform attribute initialization callback. * - * \since This datatype is available since SDL 3.0.0. + * This is called when SDL is attempting to create an EGL context, to let the + * app add extra attributes to its eglGetPlatformDisplay() call. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks */ -typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); -typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); /** * An enumeration of OpenGL configuration attributes. @@ -261,9 +422,9 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); * fail if the GL can't provide your requested attributes at a minimum, but * you should check to see exactly what you got. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ -typedef enum SDL_GLattr +typedef enum SDL_GLAttr { SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ @@ -284,64 +445,64 @@ typedef enum SDL_GLattr SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ - SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ - SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLcontextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS, SDL_GL_EGL_PLATFORM -} SDL_GLattr; +} SDL_GLAttr; /** * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLprofile -{ - SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, - SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, - SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ -} SDL_GLprofile; +typedef Uint32 SDL_GLProfile; + +#define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */ +#define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */ +#define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ + /** - * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextFlag -{ - SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, - SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, - SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG = 0x0004, - SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 -} SDL_GLcontextFlag; +typedef Uint32 SDL_GLContextFlag; + +#define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001 +#define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002 +#define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004 +#define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008 + /** * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR * attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextReleaseFlag -{ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 -} SDL_GLcontextReleaseFlag; +typedef Uint32 SDL_GLContextReleaseFlag; + +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000 +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001 + /** * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLContextResetNotification -{ - SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, - SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 -} SDL_GLContextResetNotification; +typedef Uint32 SDL_GLContextResetNotification; + +#define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000 +#define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001 + /* Function prototypes */ @@ -350,7 +511,9 @@ typedef enum SDL_GLContextResetNotification * * \returns the number of built in video drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVideoDriver */ @@ -369,7 +532,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers */ @@ -385,7 +550,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); * \returns the name of the current video driver or NULL if no driver has been * initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers * \sa SDL_GetVideoDriver @@ -397,7 +564,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); * * \returns the current system theme, light, dark, or unknown. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); @@ -410,7 +579,9 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); @@ -420,7 +591,9 @@ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); * \returns the instance ID of the primary display on success or 0 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -448,7 +621,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); @@ -462,7 +637,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa * \returns the name of a display or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -471,19 +648,22 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa /** * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the usable desktop area represented by a display, in screen @@ -499,15 +679,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayI * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the orientation of a display when it is unrotated. @@ -516,7 +698,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID di * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -529,7 +713,9 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -543,12 +729,21 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays */ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID); @@ -573,7 +768,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -587,7 +784,7 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * refresh rate default to the desktop mode if they are set to 0. The modes * are scanned with size being first priority, format being second priority, * and finally checking the refresh rate. If all the available modes are too - * small, then NULL is returned. + * small, then false is returned. * * \param displayID the instance ID of the display to query. * \param w the width in pixels of the desired display mode. @@ -596,17 +793,19 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * for the desktop refresh rate. * \param include_high_density_modes boolean to include high density modes in * the search. - * \param mode a pointer filled in with the closest display mode equal to or - * larger than the desired mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closest a pointer filled in with the closest display mode equal to + * or larger than the desired mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes, SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest); /** * Get information about the desktop's display mode. @@ -620,7 +819,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Dis * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayMode * \sa SDL_GetDisplays @@ -639,7 +840,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDisplays @@ -653,7 +856,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SD * \returns the instance ID of the display containing the point or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -668,7 +873,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point * closest to the center of the rect on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -683,7 +890,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect * * on success or 0 on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -701,7 +910,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowDisplayScale */ @@ -725,7 +936,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window); * \returns the display scale, or 0.0f on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); @@ -743,24 +956,26 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * taken effect. * * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an - * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new - * mode dimensions. + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode + * dimensions. * * \param window the window to affect. * \param mode a pointer to the display mode to use, which can be NULL for * borderless fullscreen desktop mode, or one of the fullscreen * modes returned by SDL_GetFullscreenDisplayModes() to set an * exclusive fullscreen mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreen * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); /** * Query the display mode to use when a window is visible at fullscreen. @@ -769,7 +984,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *win * \returns a pointer to the exclusive fullscreen mode to use or NULL for * borderless fullscreen desktop mode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -785,7 +1002,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode( * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); @@ -797,7 +1016,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); @@ -811,7 +1032,9 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); @@ -870,7 +1093,7 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). * * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. * * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, * SDL_CreateWindow() will fail. @@ -890,8 +1113,11 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindowAndRenderer * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindowWithProperties * \sa SDL_DestroyWindow @@ -901,36 +1127,41 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int /** * Create a child popup window of the specified parent window. * - * 'flags' **must** contain exactly one of the following: - - * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any - * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu. - * The topmost popup menu will implicitly gain the keyboard focus. + * The flags parameter **must** contain at least one of the following: + * + * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any + * input events. + * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost + * popup menu will implicitly gain the keyboard focus. * * The following flags are not relevant to popup window creation and will be * ignored: * - * - 'SDL_WINDOW_MINIMIZED' - * - 'SDL_WINDOW_MAXIMIZED' - * - 'SDL_WINDOW_FULLSCREEN' - * - 'SDL_WINDOW_BORDERLESS' + * - `SDL_WINDOW_MINIMIZED` + * - `SDL_WINDOW_MAXIMIZED` + * - `SDL_WINDOW_FULLSCREEN` + * - `SDL_WINDOW_BORDERLESS` + * + * The following flags are incompatible with popup window creation and will + * cause it to fail: + * + * - `SDL_WINDOW_UTILITY` + * - `SDL_WINDOW_MODAL` * * The parent parameter **must** be non-null and a valid window. The parent of * a popup window can be either a regular, toplevel window, or another popup * window. * * Popup windows cannot be minimized, maximized, made fullscreen, raised, - * flash, be made a modal window, be the parent of a modal window, or grab the - * mouse and/or keyboard. Attempts to do so will fail. + * flash, be made a modal window, be the parent of a toplevel window, or grab + * the mouse and/or keyboard. Attempts to do so will fail. * * Popup windows implicitly do not have a border/decorations and do not appear * on the taskbar/dock or in lists of windows such as alt-tab menus. * - * If a parent window is hidden, any child popup windows will be recursively - * hidden as well. Child popup windows not explicitly hidden will be restored - * when the parent is shown. - * - * If the parent window is destroyed, any child popup windows will be - * recursively destroyed as well. + * If a parent window is hidden or destroyed, any child popup windows will be + * recursively hidden or destroyed as well. Child popup windows not explicitly + * hidden will be restored when the parent is shown. * * \param parent the parent of the window, must not be NULL. * \param offset_x the x position of the popup window relative to the origin @@ -944,7 +1175,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_CreateWindowWithProperties @@ -987,7 +1220,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used * with OpenGL rendering * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the - * parent of this window, required for windows with the "toolip", "menu", + * parent of this window, required for windows with the "tooltip", "menu", * and "modal" properties * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be * resizable @@ -1003,10 +1236,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * * These are additional supported properties on macOS: * @@ -1024,8 +1259,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * [README/wayland](README/wayland) for more information on using custom * surfaces. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the - * application wants an associated `wl_egl_window` object to be created, - * even if the window does not have the OpenGL property or flag set. + * application wants an associated `wl_egl_window` object to be created and + * attached to the window, even if the window does not have the OpenGL + * property or `SDL_WINDOW_OPENGL` flag set. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface * associated with the window, if you want to wrap an existing window. See * [README/wayland](README/wayland) for more information. @@ -1061,7 +1297,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateWindow @@ -1114,7 +1352,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFromID */ @@ -1130,7 +1370,9 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window); * \returns the window associated with `id` or NULL if it doesn't exist; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowID */ @@ -1143,7 +1385,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id); * \returns the parent of the window on success or NULL if the window has no * parent. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow */ @@ -1181,7 +1425,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)` * UIWindow associated with the window * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag - * assocated with metal views on the window + * associated with metal views on the window * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's * framebuffer object. It must be bound when rendering to the screen using * OpenGL. @@ -1206,6 +1450,11 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag * assocated with metal views on the window * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the + * associated overlay window. + * * On Vivante: * * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType @@ -1215,11 +1464,6 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with * the window * - * On UWP: - * - * - `SDL_PROP_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow - * associated with the window - * * On Windows: * * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window @@ -1237,6 +1481,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * the window * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window * associated with the window * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated @@ -1263,7 +1509,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); @@ -1283,15 +1531,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window #define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev" #define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window" #define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag" +#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id" #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" -#define SDL_PROP_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window" #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" #define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display" #define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface" +#define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport" #define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window" #define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface" #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel" @@ -1308,7 +1557,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window * \param window the window to query. * \returns a mask of the SDL_WindowFlags associated with `window`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_HideWindow @@ -1327,14 +1578,16 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * * \param window the window to change. * \param title the desired window title in UTF-8 format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowTitle */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); /** * Get the title of a window. @@ -1343,7 +1596,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, cons * \returns the title of the window in UTF-8 format or "" if there is no * title. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowTitle */ @@ -1364,23 +1619,24 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); * * \param window the window to change. * \param icon an SDL_Surface structure containing the icon for the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); /** * Request that the window's position be set. * - * If, at the time of this request, the window is in a fixed-size state such - * as maximized, this request may be deferred until the window returns to a - * resizable state. + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. * * This can be used to reposition fullscreen-desktop windows onto a different - * display, however, exclusive fullscreen windows are locked to a specific - * display and can only be repositioned programmatically via + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via * SDL_SetWindowFullscreenMode(). * * On some windowing systems this request is asynchronous and the new @@ -1401,15 +1657,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_S * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * `SDL_WINDOWPOS_UNDEFINED`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); /** * Get the position of a window. @@ -1425,24 +1683,25 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, i * NULL. * \param y a pointer filled in with the y position of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowPosition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); /** * Request that the size of a window's client area be set. * - * If, at the time of this request, the window in a fixed-size state, such as - * maximized or fullscreen, the request will be deferred until the window - * exits this state and becomes resizable again. + * If the window is in a fullscreen or maximized state, this request has no + * effect. * - * To change the fullscreen mode of a window, use - * SDL_SetWindowFullscreenMode() + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). * * On some windowing systems, this request is asynchronous and the new window * size may not have have been applied immediately upon the return of this @@ -1459,16 +1718,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, i * \param window the window to change. * \param w the width of the window, must be > 0. * \param h the height of the window, must be > 0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); /** * Get the size of a window's client area. @@ -1480,16 +1741,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w * \param window the window to query the width and height from. * \param w a pointer filled in with the width of the window, may be NULL. * \param h a pointer filled in with the height of the window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize * \sa SDL_GetWindowSizeInPixels * \sa SDL_SetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); /** * Get the safe area for this window. @@ -1497,19 +1760,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int * * Some devices have portions of the screen which are partially obscured or * not interactive, possibly due to on-screen controls, curved edges, camera * notches, TV overscan, etc. This function provides the area of the window - * which is safe to have interactible content. You should continue rendering + * which is safe to have interactable content. You should continue rendering * into the rest of the window, but it should not contain visually important * or interactible content. * * \param window the window to query. * \param rect a pointer filled in with the client area that is safe for * interactive content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); /** * Request that the aspect ratio of a window's client area be set. @@ -1540,15 +1805,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, S * limit. * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); /** * Get the size of a window's client area. @@ -1558,19 +1825,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window * window, may be NULL. * \param max_aspect a pointer filled in with the maximum aspect ratio of the * window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowAspectRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); /** * Get the size of a window's borders (decorations) around the client area. * - * Note: If this function fails (returns -1), the size values will be + * Note: If this function fails (returns false), the size values will be * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the * window in question was borderless. * @@ -1580,7 +1849,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * window has been presented and composited, so that the window system has a * chance to decorate the window and provide the border dimensions to SDL. * - * This function also returns -1 if getting the information is not supported. + * This function also returns false if getting the information is not + * supported. * * \param window the window to query the size values of the border * (decorations) from. @@ -1592,14 +1862,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; * NULL is permitted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); /** * Get the size of a window's client area, in pixels. @@ -1609,15 +1881,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window * NULL. * \param h a pointer to variable for storing the height in pixels, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); /** * Set the minimum size of a window's client area. @@ -1625,15 +1899,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *windo * \param window the window to change. * \param min_w the minimum width of the window, or 0 for no limit. * \param min_h the minimum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); /** * Get the minimum size of a window's client area. @@ -1643,15 +1919,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the minimum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); /** * Set the maximum size of a window's client area. @@ -1659,15 +1937,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window * \param window the window to change. * \param max_w the maximum width of the window, or 0 for no limit. * \param max_h the maximum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); /** * Get the maximum size of a window's client area. @@ -1677,15 +1957,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the maximum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); /** * Set the border state of a window. @@ -1697,15 +1979,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window * You can't change the border state of a fullscreen window. * * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bool bordered); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); /** * Set the user-resizable state of a window. @@ -1717,15 +2001,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, S * You can't change the resizable state of a fullscreen window. * * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_bool resizable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); /** * Set the window to always be above the others. @@ -1734,43 +2020,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, * will bring the window to the front and keep the window above the rest. * * \param window the window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param on_top true to set the window always on top, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL_bool on_top); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); /** * Show a window. * * \param window the window to show. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); /** * Hide a window. * * \param window the window to hide. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); /** * Request that a window be raised above other windows and gain the input @@ -1783,12 +2075,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); /** * Request that the window be made as large as possible. @@ -1811,22 +2105,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); * and Wayland window managers may vary. * * \param window the window to maximize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MinimizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); /** * Request that the window be minimized to an iconic representation. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window - * state may not have have been applied immediately upon the return of this + * state may not have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to * block until the changes have taken effect. * @@ -1835,21 +2134,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to minimize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); /** * Request that the size and position of a minimized or maximized window be * restored. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1860,16 +2164,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to restore. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_MinimizeWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); /** * Request that the window's fullscreen state be changed. @@ -1888,18 +2194,20 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); * is just a request, it can be denied by the windowing system. * * \param window the window to change. - * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed - * mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); /** * Block until any pending window state is finalized. @@ -1915,10 +2223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * * \param window the window for which to wait for the pending state to be * applied. - * \returns SDL_TRUE on success or SDL_FALSE if the operation timed out before - * the window was in the requested state. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSize * \sa SDL_SetWindowPosition @@ -1928,20 +2238,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * \sa SDL_RestoreWindow * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SyncWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); /** * Return whether the window has a surface associated with it. * * \param window the window to query. - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. + * \returns true if there is a surface associated with the window, or false + * otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); /** * Get the SDL surface associated with the window. @@ -1961,7 +2273,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyWindowSurface * \sa SDL_WindowHasSurface @@ -1985,14 +2299,16 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * * \param window the window. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) @@ -2003,14 +2319,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *windo * \param window the window to query. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetWindowSurfaceVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); /** * Copy the window surface to the screen. @@ -2021,15 +2339,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *windo * This function is equivalent to the SDL 1.2 API SDL_Flip(). * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); /** * Copy areas of the window surface to the screen. @@ -2048,29 +2368,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window) * \param rects an array of SDL_Rect structures representing areas of the * surface to copy, in pixels. * \param numrects the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); /** * Destroy the surface associated with the window. * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); /** * Set a window's keyboard grab mode. @@ -2092,16 +2416,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window * other window loses its grab in favor of the caller's window. * * \param window the window for which the keyboard grab mode should be set. - * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab keyboard, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); /** * Set a window's mouse grab mode. @@ -2109,47 +2435,60 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *windo * Mouse grab confines the mouse cursor to the window. * * \param window the window for which the mouse grab mode should be set. - * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab mouse, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * - * \sa SDL_GetWindowMouseGrab + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); /** * Get a window's keyboard grab mode. * * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \returns true if keyboard is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); /** * Get a window's mouse grab mode. * * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \returns true if mouse is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); /** * Get the window that currently has an input grab enabled. * * \returns the window if input is grabbed or NULL otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab @@ -2165,15 +2504,18 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \param window the window that will be associated with the barrier. * \param rect a rectangle area in window-relative coordinates. If NULL the * barrier for the specified window will be destroyed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); /** * Get the mouse confinement rectangle of a window. @@ -2182,9 +2524,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, * \returns a pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab */ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window); @@ -2194,18 +2540,20 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * * The parameter `opacity` will be clamped internally between 0.0f * (transparent) and 1.0f (opaque). * - * This function also returns -1 if setting the opacity isn't supported. + * This function also returns false if setting the opacity isn't supported. * * \param window the window which will be made transparent or opaque. * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowOpacity */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); /** * Get the opacity of a window. @@ -2217,43 +2565,81 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, fl * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowOpacity */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); /** - * Set the window as a modal to a parent window. + * Set the window as a child of a parent window. * - * If the window is already modal to an existing window, it will be reparented - * to the new owner. Setting the parent window to null unparents the modal - * window and removes modal status. + * If the window is already the child of an existing window, it will be + * reparented to the new owner. Setting the parent window to NULL unparents + * the window and removes child window status. * - * Setting a window as modal to a parent that is a descendent of the modal - * window results in undefined behavior. + * If a parent window is hidden or destroyed, the operation will be + * recursively applied to child windows. Child windows hidden with the parent + * that did not have their hidden status explicitly set will be restored when + * the parent is shown. * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModal() to cancel the modal status before + * attempting to change the parent. * - * \since This function is available since SDL 3.0.0. + * Popup windows cannot change parents and attempts to do so will fail. + * + * Setting a parent window that is currently the sibling or descendent of the + * child window results in undefined behavior. + * + * \param window the window that should become the child of a parent. + * \param parent the new parent window for the child window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowModal */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window, SDL_Window *parent_window); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); /** * Set whether the window may have input focus. * * \param window the window to set focusable state. - * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow - * input focus. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param focusable true to allow input focus, false to not allow input focus. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_bool focusable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); /** @@ -2272,17 +2658,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, * the client area. * \param y the y coordinate of the menu, relative to the origin (top-left) of * the client area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); /** * Possible return values from the SDL_HitTest callback. * - * \since This enum is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This enum is available since SDL 3.2.0. * * \sa SDL_HitTest */ @@ -2335,7 +2725,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * Specifying NULL for a callback disables hit-testing. Hit-testing is * disabled by default. * - * Platforms that don't support this functionality will return SDL_FALSE + * Platforms that don't support this functionality will return false * unconditionally, even if you're attempting to disable hit-testing. * * Your callback may fire at any time, and its firing does not indicate any @@ -2349,58 +2739,72 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \param window the window to set hit-testing on. * \param callback the function to call when doing a hit-test. * \param callback_data an app-defined void pointer passed to **callback**. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); /** * Set the shape of a transparent window. * * This sets the alpha channel of a transparent window and any fully * transparent areas are also transparent to mouse clicks. If you are using - * something besides the SDL render API, then you are responsible for setting - * the alpha channel of the window yourself. + * something besides the SDL render API, then you are responsible for drawing + * the alpha channel of the window to match the shape alpha channel to get + * consistent cross-platform results. * * The shape is copied inside this function, so you can free it afterwards. If * your shape surface changes, you should call SDL_SetWindowShape() again to - * update the window. + * update the window. This is an expensive operation, so should be done + * sparingly. * * The window must have been created with the SDL_WINDOW_TRANSPARENT flag. * * \param window the window. * \param shape the surface representing the shape of the window, or NULL to * remove any current shape. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); /** * Request a window to demand attention from the user. * * \param window the window to be flashed. * \param operation the operation to perform. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); /** * Destroy a window. * - * Any popups or modal windows owned by the window will be recursively - * destroyed as well. + * Any child windows owned by the window will be recursively destroyed as + * well. + * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. * * \param window the window to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindow @@ -2416,28 +2820,31 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. + * \returns true if the screensaver is enabled, false if it is disabled. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenSaverEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); /** * Allow the screen to be blanked by a screen saver. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); /** * Prevent the screen from being blanked by a screen saver. @@ -2448,15 +2855,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); * The screensaver is disabled by default, but this may by changed by * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); /** @@ -2476,15 +2885,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); * * \param path the platform dependent OpenGL library name, or NULL to open the * default OpenGL library. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); /** * Get an OpenGL function by name. @@ -2531,7 +2942,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); * \returns a pointer to the named OpenGL function. The returned pointer * should be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ExtensionSupported * \sa SDL_GL_LoadLibrary @@ -2550,7 +2963,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char * \returns a pointer to the named EGL function. The returned pointer should * be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EGL_GetCurrentDisplay */ @@ -2559,7 +2974,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha /** * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_LoadLibrary */ @@ -2580,16 +2997,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * every time you need to know. * * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * \returns true if the extension is supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** * Reset all previously set OpenGL context attributes to their default values. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute @@ -2604,34 +3025,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * SDL_GL_GetAttribute() to check the values after creating the OpenGL * context, since the values obtained can differ from the requested ones. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * set. * \param value the desired value for the attribute. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * get. * \param value a pointer filled in with the current value of `attr`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value); /** * Create an OpenGL context for an OpenGL window, and make it current. @@ -2648,7 +3073,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *v * \returns the OpenGL context associated with `window` or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_DestroyContext * \sa SDL_GL_MakeCurrent @@ -2662,14 +3089,16 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * * \param window the window to associate with the context. * \param context the OpenGL context to associate with the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); /** * Get the currently active OpenGL window. @@ -2677,7 +3106,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_ * \returns the currently active OpenGL window on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); @@ -2687,7 +3118,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); * \returns the currently active OpenGL context or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_MakeCurrent */ @@ -2699,7 +3132,9 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * \returns the currently active EGL display or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); @@ -2709,7 +3144,9 @@ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); * \returns the currently active EGL config or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); @@ -2720,7 +3157,9 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); * \returns the EGLSurface pointer associated with the window, or NULL on * failure. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); @@ -2728,27 +3167,25 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * Sets the callbacks for defining custom EGLAttrib arrays for EGL * initialization. * - * Each callback should return a pointer to an EGL attribute array terminated - * with EGL_NONE. Callbacks may return NULL pointers to signal an error, which - * will cause the SDL_CreateWindow process to fail gracefully. - * - * The arrays returned by each callback will be appended to the existing - * attribute arrays defined by SDL. + * Callbacks that aren't needed can be set to NULL. * * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. * * \param platformAttribCallback callback for attributes to pass to - * eglGetPlatformDisplay. + * eglGetPlatformDisplay. May be NULL. * \param surfaceAttribCallback callback for attributes to pass to - * eglCreateSurface. + * eglCreateSurface. May be NULL. * \param contextAttribCallback callback for attributes to pass to - * eglCreateContext. + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, - SDL_EGLIntArrayCallback surfaceAttribCallback, - SDL_EGLIntArrayCallback contextAttribCallback); + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); /** * Set the swap interval for the current OpenGL context. @@ -2758,7 +3195,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * the vertical retrace for a given frame, it swaps buffers immediately, which * might be less jarring for the user during occasional framerate drops. If an * application requests adaptive vsync and the system does not support it, - * this function will fail and return SDL_FALSE. In such a case, you should + * this function will fail and return false. In such a case, you should * probably retry the call with 1 for the interval. * * Adaptive vsync is implemented for some glX drivers with @@ -2770,14 +3207,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * * \param interval 0 for immediate updates, 1 for updates synchronized with * the vertical retrace, -1 for adaptive vsync. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); /** * Get the swap interval for the current OpenGL context. @@ -2789,14 +3228,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); * synchronization, 1 if the buffer swap is synchronized with * the vertical retrace, and -1 if late swaps happen * immediately instead of waiting for the next retrace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_SetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); /** * Update a window with OpenGL rendering. @@ -2809,25 +3250,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); * extra. * * \param window the window to change. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); /** * Delete an OpenGL context. * * \param context the OpenGL context to be deleted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); /* @} *//* OpenGL support functions */ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_vulkan.h b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_vulkan.h index c31d33c..5a48756 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_vulkan.h +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_vulkan.h @@ -23,11 +23,25 @@ * # CategoryVulkan * * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. */ #ifndef SDL_vulkan_h_ #define SDL_vulkan_h_ +#include #include #include @@ -55,6 +69,10 @@ VK_DEFINE_HANDLE(VkPhysicalDevice) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) struct VkAllocationCallbacks; +/* Make sure to undef to avoid issues in case of later vulkan include */ +#undef VK_DEFINE_HANDLE +#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE + #endif /* !NO_SDL_VULKAN_TYPEDEFS */ /** @@ -69,6 +87,13 @@ struct VkAllocationCallbacks; * creating any Vulkan windows. If no Vulkan loader library is loaded, the * default library will be loaded upon creation of the first Vulkan window. * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * * It is fairly common for Vulkan applications to link with libvulkan instead * of explicitly loading it at run time. This will work with SDL provided the * application links to a dynamic library and both it and SDL use the same @@ -95,15 +120,17 @@ struct VkAllocationCallbacks; * library version. * * \param path the platform dependent Vulkan loader library name or NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); /** * Get the address of the `vkGetInstanceProcAddr` function. @@ -122,14 +149,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); /** * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_LoadLibrary */ @@ -153,7 +193,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * \returns an array of extension name strings on success, NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_CreateSurface */ @@ -175,15 +215,15 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension * allocator that creates the surface. Can be NULL. * \param surface a pointer to a VkSurfaceKHR handle to output the newly * created surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_DestroySurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, const struct VkAllocationCallbacks *allocator, VkSurfaceKHR* surface); @@ -206,7 +246,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window * \param allocator a VkAllocationCallbacks struct, which lets the app set the * allocator that destroys the surface. Can be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_CreateSurface @@ -226,14 +266,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, * \param physicalDevice a valid Vulkan physical device handle. * \param queueFamilyIndex a valid queue family index for the given physical * device. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error - * occurred. + * \returns true if supported, false if unsupported or an error occurred. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/sdl3-config.cmake b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/SDL3Config.cmake similarity index 98% rename from Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/sdl3-config.cmake rename to Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/SDL3Config.cmake index 784d27d..03673f3 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/sdl3-config.cmake +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/SDL3Config.cmake @@ -59,7 +59,7 @@ if(NOT TARGET SDL3::SDL3-shared) set_target_properties(SDL3::SDL3-shared PROPERTIES FRAMEWORK "TRUE" - IMPORTED_LOCATION "${_sdl3_framework_path}/SDL3" + IMPORTED_LOCATION "${_sdl3_framework_path}" INTERFACE_LINK_LIBRARIES "SDL3::Headers" COMPATIBLE_INTERFACE_BOOL "SDL3_SHARED" INTERFACE_SDL3_SHARED "ON" diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/sdl3-config-version.cmake b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/SDL3ConfigVersion.cmake similarity index 100% rename from Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/sdl3-config-version.cmake rename to Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/CMake/SDL3ConfigVersion.cmake diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/INSTALL.md b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/INSTALL.md new file mode 100644 index 0000000..97e4ab6 --- /dev/null +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/INSTALL.md @@ -0,0 +1,41 @@ + +# Using this package + +This package contains SDL built for Xcode. + +To use this package in Xcode, drag `SDL3.framework` into your project. + +# Documentation + +An API reference, tutorials, and additional documentation is available at: + +https://wiki.libsdl.org/SDL3 + +# Example code + +There are simple example programs available at: + +https://examples.libsdl.org/SDL3 + +# Discussions + +## Discord + +You can join the official Discord server at: + +https://discord.com/invite/BwpFGBWsv8 + +## Forums/mailing lists + +You can join SDL development discussions at: + +https://discourse.libsdl.org/ + +Once you sign up, you can use the forum through the website or as a mailing list from your email client. + +## Announcement list + +You can sign up for the low traffic announcement list at: + +https://www.libsdl.org/mailing-list.php + diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/Info.plist b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/Info.plist index f7d7959..bf4b282 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/Info.plist +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/Info.plist @@ -3,7 +3,7 @@ BuildMachineOSBuild - 24B5035e + 23H311 CFBundleDevelopmentRegion English CFBundleExecutable @@ -19,7 +19,7 @@ CFBundlePackageType FMWK CFBundleShortVersionString - 3.1.2 + 3.2.0 CFBundleSignature SDLX CFBundleSupportedPlatforms @@ -27,24 +27,24 @@ MacOSX CFBundleVersion - 3.1.2 + 3.2.0 DTCompiler com.apple.compilers.llvm.clang.1_0 DTPlatformBuild - 24B5024b + DTPlatformName macosx DTPlatformVersion - 15.1 + 14.5 DTSDKBuild - 24B5024b + 23F73 DTSDKName - macosx15.1 + macosx14.5 DTXcode - 1610 + 1540 DTXcodeBuild - 16B5001e + 15F31d LSMinimumSystemVersion - 10.11 + 10.13 diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/License.txt b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/License.txt index 42f3736..23abb73 100644 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/License.txt +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/License.txt @@ -1,6 +1,4 @@ - -Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -17,3 +15,4 @@ freely, subject to the following restrictions: 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. + diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/README.md b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/README.md new file mode 100644 index 0000000..68b0923 --- /dev/null +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/README.md @@ -0,0 +1,17 @@ + +Simple DirectMedia Layer (SDL for short) is a cross-platform library +designed to make it easy to write multi-media software, such as games +and emulators. + +You can find the latest release and additional information at: +https://www.libsdl.org/ + +Installation instructions and a quick introduction is available in +[INSTALL.md](INSTALL.md) + +This library is distributed under the terms of the zlib license, +available in [LICENSE.txt](LICENSE.txt). + +Enjoy! + +Sam Lantinga (slouken@libsdl.org) diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/ReadMe.txt b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/ReadMe.txt deleted file mode 100644 index 6ea9347..0000000 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/ReadMe.txt +++ /dev/null @@ -1,44 +0,0 @@ -The Simple DirectMedia Layer (SDL for short) is a cross-platform -library designed to make it easy to write multi-media software, -such as games and emulators. - -The Simple DirectMedia Layer library source code is available from: -http://www.libsdl.org/ - -This library is distributed under the terms of the zlib license: -http://zlib.net/zlib_license.html - - -This packages contains the SDL framework for macOS. -Conforming with Apple guidelines, this framework -contains both the SDL runtime component and development header files. - - -To Install: -Copy "SDL3.xcframework" and "share" to /Library/Frameworks - -You may alternatively install it in /Library/Frameworks -if your access privileges are not high enough. - - -Use in CMake projects: -SDL3.xcframework can be used in CMake projects using the following pattern: -```cmake -find_package(SDL3 REQUIRED COMPONENTS SDL3) -add_executable(my_game ${MY_SOURCES}) -target_link_libraries(my_game PRIVATE SDL3::SDL3) -``` -If SDL3.framework is installed in a non-standard location, -please refer to the following link for ways to configure CMake: -https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure - - -Additional References: - - - Screencast tutorials for getting started with OpenSceneGraph/macOS are - available at: - http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips - Though these are OpenSceneGraph centric, the same exact concepts apply to - SDL, thus the videos are recommended for everybody getting started with - developing on macOS. (You can skim over the PlugIns stuff since SDL - doesn't have any PlugIns to worry about.) diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/compile_shaders.sh b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/compile_shaders.sh deleted file mode 100755 index ef5e744..0000000 --- a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/compile_shaders.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/bin/bash - -set -x -set -e -cd `dirname "$0"` - -shadernames=(FullscreenVert BlitFrom2D BlitFrom2DArray BlitFrom3D BlitFromCube) - -generate_shaders() -{ - fileplatform=$1 - compileplatform=$2 - sdkplatform=$3 - minversion=$4 - - for shadername in "${shadernames[@]}"; do - xcrun -sdk $sdkplatform metal -c -std=$compileplatform-metal1.1 -m$sdkplatform-version-min=$minversion -Wall -O3 -D COMPILE_$shadername -o ./$shadername.air ./Metal_Blit.metal || exit $? - xcrun -sdk $sdkplatform metallib -o $shadername.metallib $shadername.air || exit $? - xxd -i $shadername.metallib | perl -w -p -e 's/\Aunsigned /const unsigned /;' >./${shadername}_$fileplatform.h - rm -f $shadername.air $shadername.metallib - done -} - -generate_shaders macos macos macosx 10.11 -generate_shaders ios ios iphoneos 8.0 -generate_shaders iphonesimulator ios iphonesimulator 8.0 -generate_shaders tvos ios appletvos 9.0 -generate_shaders tvsimulator ios appletvsimulator 9.0 - -# Bundle together one mega-header -catShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - cat ${shadername}_$target.h >> Metal_Blit.h - done -} - -rm -f Metal_Blit.h -echo "#if defined(SDL_PLATFORM_IOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders iphonesimulator - echo "#else" >> Metal_Blit.h - catShaders ios - echo "#endif" >> Metal_Blit.h -echo "#elif defined(SDL_PLATFORM_TVOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders tvsimulator - echo "#else" >> Metal_Blit.h - catShaders tvos - echo "#endif" >> Metal_Blit.h -echo "#else" >> Metal_Blit.h - catShaders macos -echo "#endif" >> Metal_Blit.h - -# Clean up -cleanupShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - rm -f ${shadername}_$target.h - done -} -cleanupShaders iphonesimulator -cleanupShaders ios -cleanupShaders tvsimulator -cleanupShaders tvos -cleanupShaders macos \ No newline at end of file diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/default.metallib b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/default.metallib index 8eebed0..10d8cb4 100644 Binary files a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/default.metallib and b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Resources/default.metallib differ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/SDL3 b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/SDL3 index 2da620b..7ee2133 100755 Binary files a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/SDL3 and b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/SDL3 differ diff --git a/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/_CodeSignature/CodeResources b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/_CodeSignature/CodeResources new file mode 100644 index 0000000..9f33936 --- /dev/null +++ b/Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/_CodeSignature/CodeResources @@ -0,0 +1,712 @@ + + + + + files + + Resources/CMake/SDL3Config.cmake + + wVPzCDAGpS2036XQsVLmiAOr8Bc= + + Resources/CMake/SDL3ConfigVersion.cmake + + gQ+LV+T54JMbmVqczZwWryOwVns= + + Resources/INSTALL.md + + fyUlqOEcE7zuLv8JGb0kUDRY4lc= + + Resources/Info.plist + + cUcvucJdeAVUiEdpV5uHwfyA6HQ= + + Resources/LICENSE.txt + + MV/H0zYdw5DZw6QWBIZwa65FY04= + + Resources/README.md + + ED8RfQwxZj7wFttxnetM9Q6jXX4= + + Resources/default.metallib + + /n7Rttmv06hDJMXNGqZU4OsO4ow= + + + files2 + + Headers/SDL.h + + hash2 + + Cvdi4gF6iiTrPFFXBN8WVYzKuQogVno9ER2HjYHLD78= + + + Headers/SDL_assert.h + + hash2 + + GUKvmslH9JBDeZwVHFV+dJ7uRugCENjA2fi0NvkXP6o= + + + Headers/SDL_asyncio.h + + hash2 + + 6eQHTxs1vaIfPh2XJZ8Dxl4txtqcXyGNKYkEdckwbaY= + + + Headers/SDL_atomic.h + + hash2 + + PgrpKCw7TgKe8KHwM5rZiv5NmW9QXjmnbtbdlhWZpjk= + + + Headers/SDL_audio.h + + hash2 + + VvBp9u2lRJVv9qyun1cSYcFrEcFfxL8Sug+lFgPr6zU= + + + Headers/SDL_begin_code.h + + hash2 + + fxk2E7HjevknSqJuM6gdTVdk729oKqu6dGiIKlngKOI= + + + Headers/SDL_bits.h + + hash2 + + H88Gt0fGZ+U7ts+dAX1avFoprYg8Be7fz7AhxXG2FZI= + + + Headers/SDL_blendmode.h + + hash2 + + hAasxDnDlaxJ6necLTgqEtqXgyUxOY9o6DttaAzAP8U= + + + Headers/SDL_camera.h + + hash2 + + QVRcv5xfFyaG/Co9MnzrUy3C0NEo16s3zIbl6UwkUuw= + + + Headers/SDL_clipboard.h + + hash2 + + nm+rMDYWWqbnVnJ9sg8fShfLgFD1nALxB8KsBdNTuRU= + + + Headers/SDL_close_code.h + + hash2 + + zjynPn/VKTMQ/RVWksWLXoLlFvGoJn+E0K9XLIOY4+k= + + + Headers/SDL_copying.h + + hash2 + + ZENtUHjWdC8RyLCs+LyHI30V2jZxbrJVKYaotFxBmWc= + + + Headers/SDL_cpuinfo.h + + hash2 + + wDNjucbJP3UbWyU9Y2IIuqnWZYxpJoArNRaXNrlvGu8= + + + Headers/SDL_dialog.h + + hash2 + + uSXny36TRgIvEu9/b3g7AVOwfCSVETRcNiyye6ptSMU= + + + Headers/SDL_egl.h + + hash2 + + ZI1DHIxRuv6skDbbF8PuX96mtre4/huG2LdUFjDXzds= + + + Headers/SDL_endian.h + + hash2 + + 37jA4lsA1YiTsAWGk5vvZj/H/tf4+yDoCf7vcJa9Ew0= + + + Headers/SDL_error.h + + hash2 + + fSlLo+mUuJpCvGNG5+Wb/4L7zi0FD3zbGJ2PRfMXlfI= + + + Headers/SDL_events.h + + hash2 + + 6B7T1/y4oKgsbog2B2QL6UZ4vv4UnNRnk1Lhi807z3Q= + + + Headers/SDL_filesystem.h + + hash2 + + bR6AD/KyDeLQQW98aBfdbxGzufw7+4C+WDTjBpRmy9I= + + + Headers/SDL_gamepad.h + + hash2 + + TGeZjBGUlOjcgkIzBwKK2YpN508+deGN8RMmwTx3hRI= + + + Headers/SDL_gpu.h + + hash2 + + 2tUSvuo5Ev+GaOaDzcaLUYmJT5z1/Qxi4rfF/ejz4IE= + + + Headers/SDL_guid.h + + hash2 + + lYJzCv4bmAURGxZ8Yv7DmXsFLoA0VShvmZPDA8M6z7U= + + + Headers/SDL_haptic.h + + hash2 + + qLujijGSmObisRAEHA+3sUS2/sicBu5CiFRULbc9tw8= + + + Headers/SDL_hidapi.h + + hash2 + + BS/UNHgeoUgUP0ZE7Wr1ElicSkMtMcXZRy0vOU1OsWs= + + + Headers/SDL_hints.h + + hash2 + + zZW0/QZMSL38EomWyrpmd/wrv5wgUFUbQL1T+Liy/fE= + + + Headers/SDL_init.h + + hash2 + + X1qr3eJdWv9RNxQK9U/hAHM/7fyvLI8fbHE4pQqdSIo= + + + Headers/SDL_intrin.h + + hash2 + + YlLnI56pNm7vQnEwH6oDfki+eqMkQ0FPStKovXGGxmY= + + + Headers/SDL_iostream.h + + hash2 + + 2wZxMiUAboSqkmYgGObh9demGS4uXGetGIOddzOoBxU= + + + Headers/SDL_joystick.h + + hash2 + + r0aPy8paE7O55PiB3ku4l++dZITgfb2mBLYkZXPzg7U= + + + Headers/SDL_keyboard.h + + hash2 + + QMAEiiN+f9SUaPFtczb4DFrl44iMPNHXveQxWfYGgq0= + + + Headers/SDL_keycode.h + + hash2 + + CGHx7BS7/S7d8qMTXN1PVcyq+oGig+V0AjbvTRDo5wA= + + + Headers/SDL_loadso.h + + hash2 + + LucDpNvlT+qEmAE0wm0hy4fDDfS3r9+ho8xspu9k4J4= + + + Headers/SDL_locale.h + + hash2 + + s0UA/AyUaFIR/UxuFbAnLzul37UAYEB8OQHGyemDmFs= + + + Headers/SDL_log.h + + hash2 + + 0ypVf/5dM6mKA3D2BbkFRVoQaIuqUEDMEu1d5a59kak= + + + Headers/SDL_main.h + + hash2 + + dExUeHgHxUtHVpvJKFF6GLiPaRKS2UZ84V8JwgNYn/c= + + + Headers/SDL_main_impl.h + + hash2 + + nLJhKmOzMf/3oNn8MHvp28Ph8hx7CuZOgYGvyxa0Fg8= + + + Headers/SDL_messagebox.h + + hash2 + + f9JqShergM7ApYxHQJp0rMwnRA2TW3m1COEQmJgrwMg= + + + Headers/SDL_metal.h + + hash2 + + 7Fs5+iU7qLHNh8XkDvbeNtwypYjyDVB4sBEoASSwgkA= + + + Headers/SDL_misc.h + + hash2 + + zlOAZjhmbs3kUq4/i86aZTyFOf54uMb9lYW9SIjsk+A= + + + Headers/SDL_mouse.h + + hash2 + + YjZ7PHxJHE7eO4DD5IZ1dJmRmr1AK94SCg+xivpEFqw= + + + Headers/SDL_mutex.h + + hash2 + + K0mA/DdrF5+fAYkt6vZ5qNonce+zAecF0f+2ay6eciU= + + + Headers/SDL_oldnames.h + + hash2 + + pGGsTEnGS1qN38nfrQooK1X/CM4p6EhYwHuSrUCuZCE= + + + Headers/SDL_opengl.h + + hash2 + + LqWxBvkb9UooP3YdPv2hhaUV7Z1hcCrHNXJ0kg5pIC4= + + + Headers/SDL_opengl_glext.h + + hash2 + + 2IXkrwf1MIPKwa6QphzLOTF5R+5z5SFlBvsl9q5QMyQ= + + + Headers/SDL_opengles.h + + hash2 + + q8cYr3RT0WnR58ff37XZOaJQUZvuAt99QuDWplt+DIU= + + + Headers/SDL_opengles2.h + + hash2 + + 0ENhHFweBuRmpiO4jR7kmHRilduMwfFfGHLBl0IEUhc= + + + Headers/SDL_opengles2_gl2.h + + hash2 + + 1uxEsdc/OvzjogrGl223+z2sZWxRkPC1Y+TOkNeaFao= + + + Headers/SDL_opengles2_gl2ext.h + + hash2 + + T8WwA03N6cElki4+cNAUiaazNQdoVu5mApThpjBaNxk= + + + Headers/SDL_opengles2_gl2platform.h + + hash2 + + R3m+mZrNGQRFgjjwnIaYO3lgrEDmEuBdstuX22FfHg8= + + + Headers/SDL_opengles2_khrplatform.h + + hash2 + + ex4Bqqetj2/DS1x733nr9RibsJ4sTS55/F01BiPRHoM= + + + Headers/SDL_pen.h + + hash2 + + kMVe4rIilC0D2bCBXaQuTbyJcfYuFB6NF2zY0GMHZSc= + + + Headers/SDL_pixels.h + + hash2 + + LNF1mr8/q/ySYmhjN3BTRHUt8uoP0y2eaqGUSd01l1Q= + + + Headers/SDL_platform.h + + hash2 + + rJzzCb3cDnVV++HUJYN7rROraIegCilBvo1PzfSzERo= + + + Headers/SDL_platform_defines.h + + hash2 + + 1gY0D+xDbD99hyMrgCSftn/D98qE6Yzn384cCqguVQU= + + + Headers/SDL_power.h + + hash2 + + d9umbBzotQlz1MRiww4CcbV9plDfGYfg3LaoLI3Scro= + + + Headers/SDL_process.h + + hash2 + + Z6C8A6FVpoIFvmXDeVS57eD4WN5vSQcIcaKjUB9vmAQ= + + + Headers/SDL_properties.h + + hash2 + + FMSMnEfaIzvmuD/o5CBL6rhd6pXGuhrkjmSQ1F6mTt8= + + + Headers/SDL_rect.h + + hash2 + + dlouxLVTArPG98yxRQqcSEB/uMsozkfdcpTtRIU4Ojs= + + + Headers/SDL_render.h + + hash2 + + TTzckAGMIupcnJuLd1+U5SiZgRfytR/bTs1yRoWV56E= + + + Headers/SDL_revision.h + + hash2 + + kzj2kc5o0jOr8L5Dp5XLTtDRK+/WBebI7bVi3oVcjqA= + + + Headers/SDL_scancode.h + + hash2 + + Mz+cUcJxVYNH1PgH1HQ1lms9b/w6rFkgovMaKX/MFfs= + + + Headers/SDL_sensor.h + + hash2 + + hkGEpyGOUWQhmMkuMasy86uqDchGDP1O8OLMic0d45M= + + + Headers/SDL_stdinc.h + + hash2 + + 1lQYyQZpVGCCIEVg1wB60YfE/4v9zVXcNgevbNJRLPs= + + + Headers/SDL_storage.h + + hash2 + + oxSWVHUbbqMKvx1QBuV39bmyH+VFJj/wE9axnBIA0t4= + + + Headers/SDL_surface.h + + hash2 + + Js/qrm2ltYV2bTT/AUSXIgbmPDb21TuhNGd+j91G6Bs= + + + Headers/SDL_system.h + + hash2 + + j+vc/6qa/tWwnNVuxFtl/+ZasjDpFiKIj/SWs9WvmoA= + + + Headers/SDL_thread.h + + hash2 + + zNaMperhXe4mP0ZQ9LMd/CewmlKkw4xTJpKu7FlubnA= + + + Headers/SDL_time.h + + hash2 + + 2uMjroK2pJQqTpQYR37U8oTurEuBWWavK4ypNIQrjiI= + + + Headers/SDL_timer.h + + hash2 + + 5hkyTURkMquzzC9SGKwImyNFwA5FTsUrX8cj8Tfkvzw= + + + Headers/SDL_touch.h + + hash2 + + IkjbfrMdhQ3G93hAl6yyUMG6/mUIs+kVUEeP//1GUmE= + + + Headers/SDL_tray.h + + hash2 + + KA3SCxpjMIcM5EeEHC6F3o9/5CFr8kAVvsd8Ra+pUms= + + + Headers/SDL_version.h + + hash2 + + 227opDjmxbL8YKwXKqGjwoVvSgAOjqD/x5Gz0fDdC7A= + + + Headers/SDL_video.h + + hash2 + + Yb5Cg96tQZZ0ErDNn2e33TSvsXYbcUYgShi8M3jkjHk= + + + Headers/SDL_vulkan.h + + hash2 + + yHTw0Wf4WcYGEJtGQKPo0qMY51hlnmVhLCebseJiLwg= + + + Resources/CMake/SDL3Config.cmake + + hash2 + + 0X7VyiYqUwqsTjqO580GDglfMgEgRhK7uFFUgPccqrk= + + + Resources/CMake/SDL3ConfigVersion.cmake + + hash2 + + o4od03lMXeFmSf7XQVrg+cMoEnzDAA0bJIE6oslEQe0= + + + Resources/INSTALL.md + + hash2 + + cfN7quEEdthPBp+Ef9Fnvue8PyOFBgmdeNoftdFDzR8= + + + Resources/Info.plist + + hash2 + + c5QStNoKK6s1PYZgb3GC0WZocAlRKD9dK0xy02Nleco= + + + Resources/LICENSE.txt + + hash2 + + l/NbMCs2FoDsHokeldLVIJe7lav/NhQ0kW2Z3BMF8Sc= + + + Resources/README.md + + hash2 + + QboZO+koFZBptSlJqxoTwskW+z99BRNKDR6cxw1Mfrg= + + + Resources/default.metallib + + hash2 + + cfZuGQ3DcwZ9KcoVxa3jVp0vsLMJbXysYttqEMHllro= + + + + rules + + ^Resources/ + + ^Resources/.*\.lproj/ + + optional + + weight + 1000 + + ^Resources/.*\.lproj/locversion.plist$ + + omit + + weight + 1100 + + ^Resources/Base\.lproj/ + + weight + 1010 + + ^version.plist$ + + + rules2 + + .*\.dSYM($|/) + + weight + 11 + + ^(.*/)?\.DS_Store$ + + omit + + weight + 2000 + + ^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/ + + nested + + weight + 10 + + ^.* + + ^Info\.plist$ + + omit + + weight + 20 + + ^PkgInfo$ + + omit + + weight + 20 + + ^Resources/ + + weight + 20 + + ^Resources/.*\.lproj/ + + optional + + weight + 1000 + + ^Resources/.*\.lproj/locversion.plist$ + + omit + + weight + 1100 + + ^Resources/Base\.lproj/ + + weight + 1010 + + ^[^/]+$ + + nested + + weight + 10 + + ^embedded\.provisionprofile$ + + weight + 20 + + ^version\.plist$ + + weight + 20 + + + + diff --git a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config.cmake b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/SDL3Config.cmake similarity index 98% rename from Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config.cmake rename to Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/SDL3Config.cmake index 784d27d..03673f3 100644 --- a/Frameworks/SDL3.xcframework/ios-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config.cmake +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/SDL3Config.cmake @@ -59,7 +59,7 @@ if(NOT TARGET SDL3::SDL3-shared) set_target_properties(SDL3::SDL3-shared PROPERTIES FRAMEWORK "TRUE" - IMPORTED_LOCATION "${_sdl3_framework_path}/SDL3" + IMPORTED_LOCATION "${_sdl3_framework_path}" INTERFACE_LINK_LIBRARIES "SDL3::Headers" COMPATIBLE_INTERFACE_BOOL "SDL3_SHARED" INTERFACE_SDL3_SHARED "ON" diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/sdl3-config-version.cmake b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/SDL3ConfigVersion.cmake similarity index 100% rename from Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/sdl3-config-version.cmake rename to Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/CMake/SDL3ConfigVersion.cmake diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL.h index c963394..861c404 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -20,9 +20,12 @@ */ /** - * \file SDL.h + * Main include header for the SDL library, version 3.2.0 * - * Main include header for the SDL library, version 3.1.2 + * It is almost always best to include just this one header instead of + * picking out individual headers included here. There are exceptions to + * this rule--SDL_main.h is special and not included here--but usually + * letting SDL.h include the kitchen sink for you is the correct approach. */ #ifndef SDL_h_ @@ -30,6 +33,7 @@ #include #include +#include #include #include #include @@ -65,6 +69,7 @@ #include #include #include +#include #include #include #include @@ -76,6 +81,7 @@ #include #include #include +#include #include #include #include diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_assert.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_assert.h index f5f798e..09b3b47 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_assert.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_assert.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,9 +51,14 @@ * - It provides statistics and data on all failed assertions to the app. * - It allows the default assertion handler to be controlled with environment * variables, in case an automated script needs to control it. + * - It can be used as an aid to Clang's static analysis; it will treat SDL + * assertions as universally true (under the assumption that you are serious + * about the asserted claims and that your debug builds will detect when + * these claims were wrong). This can help the analyzer avoid false + * positives. * - * To use it: do a debug build and just sprinkle around tests to check your - * code! + * To use it: compile a debug build and just sprinkle around tests to check + * your code! */ #ifndef SDL_assert_h_ @@ -84,7 +89,7 @@ extern "C" { * - 3: Paranoid settings: All SDL assertion macros enabled, including * SDL_assert_paranoid. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors @@ -113,24 +118,27 @@ extern "C" { * * If the program is not running under a debugger, SDL_TriggerBreakpoint will * likely terminate the app, possibly without warning. If the current platform - * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro - * does nothing. + * isn't supported, this macro is left undefined. * - * \threadsafety It is safe to call this function from any thread. + * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner -#elif defined(_MSC_VER) +#elif 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) #include #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__)) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) @@ -147,18 +155,40 @@ extern "C" { #include #define SDL_TriggerBreakpoint() raise(SIGTRAP) #else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ #endif -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FUNCTION __FUNCTION__ + +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ # define SDL_FUNCTION __func__ #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) # define SDL_FUNCTION __FUNCTION__ #else # define SDL_FUNCTION "???" #endif + +/** + * A macro that reports the current file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FILE __FILE__ + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_LINE __LINE__ /* @@ -176,14 +206,50 @@ This also solves the problem of... disable assertions. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro for wrapping code in `do {} while (0);` without compiler warnings. + * + * Visual Studio with really aggressive warnings enabled needs this to avoid + * compiler complaints. + * + * the `do {} while (0);` trick is useful for wrapping code in a macro that + * may or may not be a single statement, to avoid various C language + * accidents. + * + * To use: + * + * ```c + * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0)); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NULL_WHILE_LOOP_CONDITION (0) + +#elif defined(_MSC_VER) /* Avoid /W4 warnings. */ /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking this condition isn't constant. And looks like an owl's face! */ -#ifdef _MSC_VER /* stupid /W4 warnings. */ #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) #else #define SDL_NULL_WHILE_LOOP_CONDITION (0) #endif +/** + * The macro used when an assertion is disabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is disabled (perhaps in a release build). + * + * The code does nothing, but wraps `condition` in a sizeof operator, which + * generates no code and has no side effects, but avoid compiler warnings + * about unused variables. + * + * \param condition the condition to assert (but not actually run here). + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -198,7 +264,7 @@ disable assertions. * condition, try to break in a debugger, kill the program, or ignore the * problem). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AssertState { @@ -216,11 +282,11 @@ typedef enum SDL_AssertState * used by the assertion handler, then added to the assertion report. This is * returned as a linked list from SDL_GetAssertionReport(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AssertData { - SDL_bool always_ignore; /**< SDL_TRUE if app should always continue when assertion is triggered. */ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ const char *condition; /**< A string of this assert's test code. */ const char *filename; /**< The source file where this assert lives. */ @@ -232,7 +298,7 @@ typedef struct SDL_AssertData /** * Never call this directly. * - * Use the SDL_assert* macros instead. + * Use the SDL_assert macros instead. * * \param data assert data structure. * \param func function name. @@ -240,29 +306,57 @@ typedef struct SDL_AssertData * \param line line number. * \returns assert state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN; -/* Define the trigger breakpoint call used in asserts */ -#ifndef SDL_AssertBreakpoint -#if defined(ANDROID) && defined(assert) -/* Define this as empty in case assert() is defined as SDL_assert */ -#define SDL_AssertBreakpoint() -#else + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The macro used when an assertion triggers a breakpoint. + * + * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint + * instead. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() -#endif + +#elif !defined(SDL_AssertBreakpoint) +# if defined(ANDROID) && defined(assert) + /* Define this as empty in case assert() is defined as SDL_assert */ +# define SDL_AssertBreakpoint() +# else +# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() +# endif #endif /* !SDL_AssertBreakpoint */ -/* the do {} while(0) avoids dangling else problems: - if (x) SDL_assert(y); else blah(); - ... without the do/while, the "else" could attach to this macro's "if". - We try to handle just the minimum we need here in a macro...the loop, - the static vars, and break points. The heavy lifting is handled in - SDL_ReportAssertion(), in SDL_assert.c. -*/ +/** + * The macro used when an assertion is enabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is enabled. + * + * The `do {} while(0)` avoids dangling else problems: + * + * ```c + * if (x) SDL_assert(y); else blah(); + * ``` + * + * ... without the do/while, the "else" could attach to this macro's "if". We + * try to handle just the minimum we need here in a macro...the loop, the + * static vars, and break points. The heavy lifting is handled in + * SDL_ReportAssertion(). + * + * \param condition the condition to assert. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ @@ -305,7 +399,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; } @@ -336,7 +432,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_release(condition) SDL_disabled_assert(condition) @@ -363,7 +461,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) @@ -389,7 +489,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * #endif /** - * An assertion test that always performed. + * An assertion test that is always performed. * * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You * almost never want to use this, as it could trigger on an end-user's system, @@ -405,7 +505,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_always(condition) SDL_enabled_assert(condition) @@ -418,7 +520,10 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. * - * \since This datatype is available since SDL 3.0.0. + * \threadsafety This callback may be called from any thread that triggers an + * assert at any time. + * + * \since This datatype is available since SDL 3.2.0. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( const SDL_AssertData *data, void *userdata); @@ -440,7 +545,9 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * fails or NULL for the default handler. * \param userdata a pointer that is passed to `handler`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -459,7 +566,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler( * \returns the default SDL_AssertionHandler that is called when an assert * triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -482,7 +591,9 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler( * was passed to SDL_SetAssertionHandler(). * \returns the SDL_AssertionHandler that is called when an assert triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAssertionHandler */ @@ -508,9 +619,15 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void ** * ``` * * \returns a list of all failed assertions or NULL if the list is empty. This - * memory should not be modified or freed by the application. + * memory should not be modified or freed by the application. This + * pointer remains valid until the next call to SDL_Quit() or + * SDL_ResetAssertionReport(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads calling + * SDL_ResetAssertionReport() simultaneously, may render the + * returned pointer invalid. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetAssertionReport */ @@ -524,7 +641,11 @@ extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); * no items. In addition, any previously-triggered assertions will be reset to * a trigger_count of zero, and their always_ignore state will be false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads triggering an + * assertion, or simultaneously calling this function may cause + * memory leaks or crashes. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionReport */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_asyncio.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_asyncio.h new file mode 100644 index 0000000..b36cb07 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/* WIKI CATEGORY: AsyncIO */ + +/** + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + */ + +#ifndef SDL_asyncio_h_ +#define SDL_asyncio_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOTaskType +{ + SDL_ASYNCIO_TASK_READ, /**< A read operation. */ + SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */ + SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */ +} SDL_AsyncIOTaskType; + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOResult +{ + SDL_ASYNCIO_COMPLETE, /**< request was completed without error */ + SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */ + SDL_ASYNCIO_CANCELED /**< request was canceled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AsyncIOOutcome +{ + SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + void *buffer; /**< buffer where data was read/written. */ + Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + void *userdata; /**< pointer provided by the app when starting the task */ +} SDL_AsyncIOOutcome; + +/** + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode); + +/** + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); + +/** + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); + +/** + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome); + +/** + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS); + +/** + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_asyncio_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_atomic.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_atomic.h index f159bcd..03e3fb1 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_atomic.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_atomic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -88,15 +88,16 @@ typedef int SDL_SpinLock; * doing. Please be careful using any sort of spinlock!*** * * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. + * \returns true if the lock succeeded, false if the lock is already held. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_UnlockSpinlock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); /** * Lock a spin lock by setting it to a non-zero value. @@ -106,7 +107,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockSpinlock * \sa SDL_UnlockSpinlock @@ -123,7 +126,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_TryLockSpinlock @@ -147,9 +152,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -166,7 +172,50 @@ extern __inline void SDL_CompilerBarrier(void); #endif /** - * Insert a memory release barrier. + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); + +/** + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Insert a memory release barrier (macro version). * * Memory barriers are designed to prevent reads and writes from being * reordered by the compiler and being seen out of order on multi-core CPUs. @@ -186,31 +235,47 @@ extern __inline void SDL_CompilerBarrier(void); * For more information on these semantics, take a look at the blog post: * http://preshing.com/20120913/acquire-and-release-semantics * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierReleaseFunction to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() /** - * Insert a memory acquire barrier. + * Insert a memory acquire barrier (macro version). * - * Please refer to SDL_MemoryBarrierReleaseFunction for the details! + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. * - * \threadsafety Obviously this function is safe to use from any thread at any + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_MemoryBarrierReleaseFunction + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -/* !!! FIXME: this should have documentation! */ -#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) +#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") #elif defined(__GNUC__) && defined(__aarch64__) @@ -225,8 +290,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); hard-coded at address 0xffff0fa0 */ typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() #else #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") @@ -276,9 +341,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * * \threadsafety This macro is safe to use from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay + #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */ #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__) @@ -303,9 +369,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * A type representing an atomic integer value. * * This can be used to manage a value that is synchronized across multiple - * CPUs without a race condition; when an app sets a value with SDL_AtomicSet - * all other threads, regardless of the CPU it is running on, will see that - * value when retrieved with SDL_AtomicGet, regardless of CPU caches, etc. + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. * * This is also useful for atomic compare-and-swap operations: a thread can * change the value as long as its current value matches expectations. When @@ -316,14 +383,14 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * this!). * * This is a struct so people don't accidentally use numeric operations on it - * directly. You have to use SDL_Atomic* functions. + * directly. You have to use SDL atomic functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - * \sa SDL_AtomicAdd + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt */ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; @@ -336,15 +403,16 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; * \param a a pointer to an SDL_AtomicInt variable to be modified. * \param oldval the old value. * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. + * \returns true if the atomic variable was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, int oldval, int newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); /** * Set an atomic variable to a value. @@ -360,11 +428,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicGet + * \sa SDL_GetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); /** * Get the value of an atomic variable. @@ -377,11 +445,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicSet + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); /** * Add to an atomic variable. @@ -397,12 +465,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef * \sa SDL_AtomicIncRef */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); #ifndef SDL_AtomicIncRef @@ -414,11 +482,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to an SDL_AtomicInt to increment. * \returns the previous value of the atomic variable. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef */ -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) #endif #ifndef SDL_AtomicDecRef @@ -429,16 +499,103 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * ***Note: If you don't know what this macro is for, you shouldn't use it!*** * * \param a a pointer to an SDL_AtomicInt to increment. - * \returns SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise. + * \returns true if the variable reached zero after decrementing, false + * otherwise. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicIncRef */ -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) #endif +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***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 oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * 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. + * \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.2.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***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. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + /** * Set a pointer to a new value if it is currently an old value. * @@ -448,17 +605,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to a pointer. * \param oldval the old pointer value. * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. + * \returns true if the pointer was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGetPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, void *oldval, void *newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); /** * Set a pointer to a value atomically. @@ -472,12 +629,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicGetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); /** * Get the value of a pointer atomically. @@ -490,12 +647,12 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicGetPointer(void **a); +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_audio.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_audio.h index b7a4b7b..9569382 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_audio.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_audio.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -33,8 +33,9 @@ * even if the data format changes on either side halfway through. * * An app opens an audio device and binds any number of audio streams to it, - * feeding more data to it as available. When the devices needs more data, it - * will pull it from all bound streams and mix them together for playback. + * feeding more data to the streams as available. When the device needs more + * data, it will pull it from all bound streams and mix them together for + * playback. * * Audio streams can also use an app-provided callback to supply data * on-demand, which maps pretty closely to the SDL2 audio model. @@ -43,6 +44,45 @@ * if you aren't reading from a file) as a basic means to load sound data into * your program. * + * ## Logical audio devices + * + * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a + * logical device ID that you can bind audio streams to. In almost all cases, + * logical devices can be used anywhere in the API that a physical device is + * normally used. However, since each device opening generates a new logical + * device, different parts of the program (say, a VoIP library, or + * text-to-speech framework, or maybe some other sort of mixer on top of SDL) + * can have their own device opens that do not interfere with each other; each + * logical device will mix its separate audio down to a single buffer, fed to + * the physical device, behind the scenes. As many logical devices as you like + * can come and go; SDL will only have to open the physical device at the OS + * level once, and will manage all the logical devices on top of it + * internally. + * + * One other benefit of logical devices: if you don't open a specific physical + * device, instead opting for the default, SDL can automatically migrate those + * logical devices to different hardware as circumstances change: a user + * plugged in headphones? The system default changed? SDL can transparently + * migrate the logical devices to the correct physical device seamlessly and + * keep playing; the app doesn't even have to know it happened if it doesn't + * want to. + * + * ## Simplified audio + * + * As a simplified model for when a single source of audio is all that's + * needed, an app can use SDL_OpenAudioDeviceStream, which is a single + * function to open an audio device, create an audio stream, bind that stream + * to the newly-opened device, and (optionally) provide a callback for + * obtaining audio data. When using this function, the primary interface is + * the SDL_AudioStream and the device handle is mostly hidden away; destroying + * a stream created through this function will also close the device, stream + * bindings cannot be changed, etc. One other quirk of this is that the device + * is started in a _paused_ state and must be explicitly resumed; this is + * partially to offer a clean migration for SDL2 apps and partially because + * the app might have to do more setup before playback begins; in the + * non-simplified form, nothing will play until a stream is bound to a device, + * so they start _unpaused_. + * * ## Channel layouts * * Audio data passing through SDL is uncompressed PCM data, interleaved. One @@ -73,7 +113,7 @@ * - 4 channels (quad) layout: FL, FR, BL, BR * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be - * BL, BR) + * SL, SR) * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR * @@ -94,7 +134,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -102,19 +141,73 @@ extern "C" { #endif -/* masks for different parts of SDL_AudioFormat. */ +/** + * Mask of bits in an SDL_AudioFormat that contains the format bit size. + * + * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BITSIZE (0xFFu) + +/** + * Mask of bits in an SDL_AudioFormat that contain the floating point flag. + * + * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_FLOAT (1u<<8) + +/** + * Mask of bits in an SDL_AudioFormat that contain the bigendian flag. + * + * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN + * instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12) + +/** + * Mask of bits in an SDL_AudioFormat that contain the signed data flag. + * + * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_SIGNED (1u<<15) -#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \ - (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) +/** + * Define an SDL_AudioFormat value. + * + * SDL does not support custom audio formats, so this macro is not of much use + * externally, but it can be illustrative as to what the various bits of an + * SDL_AudioFormat mean. + * + * For example, SDL_AUDIO_S32LE looks like this: + * + * ```c + * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32) + * ``` + * + * \param signed 1 for signed data, 0 for unsigned data. + * \param bigendian 1 for bigendian data, 0 for littleendian data. + * \param flt 1 for floating point data, 0 for integer data. + * \param size number of bits per sample. + * \returns a format value in the style of SDL_AudioFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \ + (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) /** * Audio format. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_AUDIO_BITSIZE * \sa SDL_AUDIO_BYTESIZE @@ -144,17 +237,18 @@ typedef enum SDL_AudioFormat /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ -} SDL_AudioFormat; -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_AUDIO_S16 SDL_AUDIO_S16LE -#define SDL_AUDIO_S32 SDL_AUDIO_S32LE -#define SDL_AUDIO_F32 SDL_AUDIO_F32LE -#else -#define SDL_AUDIO_S16 SDL_AUDIO_S16BE -#define SDL_AUDIO_S32 SDL_AUDIO_S32BE -#define SDL_AUDIO_F32 SDL_AUDIO_F32BE -#endif + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; /** @@ -167,7 +261,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) @@ -181,7 +275,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) @@ -195,7 +289,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) @@ -209,7 +303,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) @@ -223,7 +317,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) @@ -237,7 +331,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) @@ -251,7 +345,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) @@ -265,7 +359,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) @@ -275,7 +369,7 @@ typedef enum SDL_AudioFormat * * Zero is used to signify an invalid/null device. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_AudioDeviceID; @@ -286,7 +380,7 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu) @@ -297,14 +391,14 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu) /** * Format specifier for audio data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AudioFormat */ @@ -326,7 +420,7 @@ typedef struct SDL_AudioSpec * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) @@ -350,7 +444,7 @@ typedef struct SDL_AudioSpec * more of them, bind them to an opened audio device, and feed data to them * (or for recording, consume data from them). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -359,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream; /* Function prototypes */ -/** - * \name Driver discovery functions - * - * These functions return the list of built in audio drivers, in the - * order that they are normally initialized by default. - */ -/* @{ */ - /** * Use this function to get the number of built-in audio drivers. * @@ -384,7 +470,7 @@ typedef struct SDL_AudioStream SDL_AudioStream; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDriver */ @@ -408,12 +494,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. @@ -427,7 +512,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); @@ -453,7 +538,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioRecordingDevices @@ -482,7 +567,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioPlaybackDevices @@ -498,11 +583,10 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioPlaybackDevices * \sa SDL_GetAudioRecordingDevices - * \sa SDL_GetDefaultAudioInfo */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); @@ -532,14 +616,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI * \param spec on return, will be filled with device details. * \param sample_frames pointer to store device buffer size, in sample frames. * Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); /** * Get the current channel map of an audio device. @@ -558,7 +642,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -633,13 +717,52 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseAudioDevice * \sa SDL_GetAudioDeviceFormat */ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec); +/** + * Determine if an audio device is physical (instead of logical). + * + * An SDL_AudioDeviceID that represents physical hardware is a physical + * device; there is one for each piece of hardware that SDL can see. Logical + * devices are created by calling SDL_OpenAudioDevice or + * SDL_OpenAudioDeviceStream, and while each is associated with a physical + * device, there can be any number of logical devices on one physical device. + * + * For the most part, logical and physical IDs are interchangeable--if you try + * to open a logical device, SDL understands to assign that effort to the + * underlying physical device, etc. However, it might be useful to know if an + * arbitrary device ID is physical or logical. This function reports which. + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a physical device, false if it is logical. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid); + +/** + * Determine if an audio device is a playback device (instead of recording). + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a playback device, false if it is recording. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid); + /** * Use this function to pause audio playback on a specified device. * @@ -659,17 +782,17 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioDevice * \sa SDL_AudioDevicePaused */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to unpause audio playback on a specified device. @@ -687,17 +810,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev) * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AudioDevicePaused * \sa SDL_PauseAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to query if an audio device is paused. @@ -710,16 +833,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev * IDs will report themselves as unpaused here. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. + * \returns true if device is valid and paused, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Get the gain of an audio device. @@ -738,7 +861,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioDeviceGain */ @@ -753,8 +876,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * Audio devices default to a gain of 1.0f (no change in output). * * Physical devices may not have their gain changed, only logical devices, and - * this function will always return -1 when used on physical devices. While it - * might seem attractive to adjust several logical devices at once in this + * this function will always return false when used on physical devices. While + * it might seem attractive to adjust several logical devices at once in this * way, it would allow an app or library to interfere with another portion of * the program's otherwise-isolated devices. * @@ -767,17 +890,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \param devid the audio device on which to change gain. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDeviceGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); /** * Close a previously-opened audio device. @@ -794,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID de * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice */ @@ -819,23 +942,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * Binding a stream to a device will set its output format for playback * devices, and its input format for recording devices, so they match the * device's settings. The caller is welcome to change the other end of the - * stream's format at any time. + * stream's format at any time with SDL_SetAudioStreamFormat(). * * \param devid an audio device to bind a stream to. * \param streams an array of audio streams to bind. * \param num_streams number streams listed in the `streams` array. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams); /** * Bind a single audio stream to an audio device. @@ -845,18 +968,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devi * * \param devid an audio device to bind a stream to. * \param stream an audio stream to bind to a device. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); /** * Unbind a list of audio streams from their audio devices. @@ -867,16 +990,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid * * Unbinding a stream that isn't bound to a device is a legal no-op. * - * \param streams an array of audio streams to unbind. + * \param streams an array of audio streams to unbind. Can be NULL or contain + * NULL. * \param num_streams number streams listed in the `streams` array. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams */ -extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams); /** * Unbind a single audio stream from its audio device. @@ -884,11 +1008,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **stream * This is a convenience function, equivalent to calling * `SDL_UnbindAudioStreams(&stream, 1)`. * - * \param stream an audio stream to unbind from a device. + * \param stream an audio stream to unbind from a device. Can be NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream */ @@ -907,7 +1031,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream * \sa SDL_BindAudioStreams @@ -924,7 +1048,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_GetAudioStreamData @@ -943,7 +1067,9 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream); @@ -953,17 +1079,17 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * \param stream the SDL_AudioStream to query. * \param src_spec where to store the input audio format; ignored if NULL. * \param dst_spec where to store the output audio format; ignored if NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); /** * Change the input and output formats of an audio stream. @@ -978,23 +1104,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *s * next sound file, and start putting that new data while the previous sound * file is still queued, and everything will still play back correctly. * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * * \param stream the stream the format is being changed. * \param src_spec the new format of the audio input; if NULL, it is not * changed. * \param dst_spec the new format of the audio output; if NULL, it is not * changed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFormat * \sa SDL_SetAudioStreamFrequencyRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** * Get the frequency ratio of an audio stream. @@ -1006,7 +1138,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *s * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFrequencyRatio */ @@ -1027,18 +1159,18 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \param stream the stream the frequency ratio is being changed. * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 * and 100. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Get the gain of an audio stream. @@ -1055,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioS * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGain */ @@ -1074,17 +1206,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \param stream the stream on which the gain is being changed. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); /** * Get the current input channel map of an audio stream. @@ -1104,7 +1236,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *str * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1128,7 +1260,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStr * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1148,8 +1280,12 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * Data that was previously queued in the stream will still be operated on in * the order that was current when it was added, which is to say you can put @@ -1164,26 +1300,31 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Set the current output channel map of an audio stream. @@ -1194,12 +1335,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * The output channel map reorders data that leaving a stream via * SDL_GetAudioStreamData. * - * Each item in the array represents an output channel, and its value is the + * Each item in the array represents an input channel, and its value is the * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * The output channel map can be changed at any time, as output remapping is * applied during SDL_GetAudioStreamData. @@ -1211,26 +1356,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Add data to the stream. @@ -1246,21 +1398,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_Audi * \param stream the stream the audio data is being added to. * \param buf a pointer to the audio data to add. * \param len the number of bytes to write to the stream. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but if the * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_FlushAudioStream * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); /** * Get converted/resampled data from the stream. @@ -1284,7 +1436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *str * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_GetAudioStreamAvailable @@ -1311,7 +1463,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamData * \sa SDL_PutAudioStreamData @@ -1322,6 +1474,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str /** * Get the number of bytes currently queued. * + * This is the number of bytes put into a stream as input, not the number that + * can be retrieved as output. Because of several details, it's not possible + * to calculate one number directly from the other. If you need to know how + * much usable data can be retrieved right now, you should use + * SDL_GetAudioStreamAvailable() and not this function. + * * Note that audio streams can change their input format at any time, even if * there is still data queued in a different format, so the returned byte * count will not necessarily match the number of _sample frames_ available. @@ -1344,7 +1502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_ClearAudioStream @@ -1361,16 +1519,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * input, so the complete output becomes available. * * \param stream the audio stream to flush. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** * Clear any pending data in the stream. @@ -1379,19 +1537,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *strea * stream until more is added. * * \param stream the audio stream to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamAvailable * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); /** * Use this function to pause audio playback on the audio device associated @@ -1406,16 +1564,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *strea * loading, etc. * * \param stream the audio stream associated with the audio device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); /** * Use this function to unpause audio playback on the audio device associated @@ -1426,16 +1584,36 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream * to progress again, and audio can be generated. * * \param stream the audio stream associated with the audio device to resume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to query if an audio device associated with a stream is + * paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * \param stream the audio stream associated with the audio device to query. + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream); + /** * Lock an audio stream for serialized access. @@ -1454,16 +1632,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream * all the same attributes (recursive locks are allowed, etc). * * \param stream the audio stream to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); /** @@ -1472,17 +1650,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream * This unlocks an audio stream after a call to SDL_LockAudioStream. * * \param stream the audio stream to unlock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety You should only call this from the same thread that * previously called SDL_LockAudioStream. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); /** * A callback that fires when data passes through an SDL_AudioStream. @@ -1519,7 +1697,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stre * is called, so your callback does not need to manage the lock * explicitly. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback * \sa SDL_SetAudioStreamPutCallback @@ -1561,16 +1739,16 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * from the stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamPutCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** * Set a callback that runs when data is added to an audio stream. @@ -1610,16 +1788,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStre * stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** @@ -1637,7 +1815,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStre * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -1699,7 +1877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamDevice * \sa SDL_ResumeAudioStreamDevice @@ -1737,7 +1915,7 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_Audi * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioPostmixCallback */ @@ -1788,14 +1966,14 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio * \param devid the ID of an opened audio device. * \param callback a callback function to be called. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); /** @@ -1839,7 +2017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * Example: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); + * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len); * ``` * * Note that the SDL_LoadWAV function does this same thing for you, but in a @@ -1850,19 +2028,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * ``` * * \param src the data source for the WAVE data. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE * data's format details on successful return. * \param audio_buf a pointer filled with the audio data, allocated by the * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1871,12 +2049,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Loads a WAV from a file path. @@ -1884,7 +2062,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * This is a convenience function that is effectively the same as: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), SDL_TRUE, spec, audio_buf, audio_len); + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); * ``` * * \param path the file path of the WAV file to open. @@ -1894,11 +2072,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1907,12 +2085,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Mix audio data in a specified format. @@ -1941,14 +2119,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * \param len the length of the audio buffer in bytes. * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full * audio volume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); /** * Convert some audio data of one format to another format. @@ -1971,14 +2149,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, * which should be freed with SDL_free(). On error, it will be * NULL. * \param dst_len will be filled with the len of dst_data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); /** * Get the human readable name of an audio format. @@ -1989,7 +2167,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); @@ -2005,7 +2183,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_begin_code.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_begin_code.h index f418c61..a6b47cf 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_begin_code.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_begin_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,15 @@ /* WIKI CATEGORY: BeginCode */ /** - * SDL_begin_code.h sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * # CategoryBeginCode + * + * `SDL_begin_code.h` sets things up for C dynamic library function + * definitions, static inlined functions, and structures aligned at 4-byte + * alignment. If you don't like ugly C preprocessor code, don't look at this + * file. :) + * + * SDL's headers use this; applications generally should not include this + * header directly. */ /* This shouldn't be nested -- included it around code only. */ @@ -33,6 +39,259 @@ #endif #define SDL_begin_code_h +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a symbol as deprecated. + * + * A function is marked deprecated by adding this macro to its declaration: + * + * ```c + * extern SDL_DEPRECATED int ThisFunctionWasABadIdea(void); + * ``` + * + * Compilers with deprecation support can give a warning when a deprecated + * function is used. This symbol may be used in SDL's headers, but apps are + * welcome to use it for their own interfaces as well. + * + * SDL, on occasion, might deprecate a function for various reasons. However, + * SDL never removes symbols before major versions, so deprecated interfaces + * in SDL3 will remain available until SDL4, where it would be expected an app + * would have to take steps to migrate anyhow. + * + * On compilers without a deprecation mechanism, this is defined to nothing, + * and using a deprecated function will not generate a warning. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEPRECATED __attribute__((deprecated)) + +/** + * A macro to tag a symbol as a public API. + * + * SDL uses this macro for all its public functions. On some targets, it is + * used to signal to the compiler that this function needs to be exported from + * a shared library, but it might have other side effects. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DECLSPEC __attribute__ ((visibility("default"))) + +/** + * A macro to set a function's calling conventions. + * + * SDL uses this macro for all its public functions, and any callbacks it + * defines. This macro guarantees that calling conventions match between SDL + * and the app, even if the two were built with different compilers or + * optimization settings. + * + * When writing a callback function, it is very important for it to be + * correctly tagged with SDLCALL, as mismatched calling conventions can cause + * strange behaviors and can be difficult to diagnose. Plus, on many + * platforms, SDLCALL is defined to nothing, so compilers won't be able to + * warn that the tag is missing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDLCALL __cdecl + +/** + * A macro to request a function be inlined. + * + * This is a hint to the compiler to inline a function. The compiler is free + * to ignore this request. On compilers without inline support, this is + * defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INLINE __inline + +/** + * A macro to demand a function be inlined. + * + * This is a command to the compiler to inline a function. SDL uses this macro + * in its public headers for a handful of simple functions. On compilers + * without forceinline support, this is defined to `static SDL_INLINE`, which + * is often good enough. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FORCE_INLINE __forceinline + +/** + * A macro to tag a function as never-returning. + * + * This is a hint to the compiler that a function does not return. An example + * of a function like this is the C runtime's exit() function. + * + * This hint can lead to code optimizations, and help analyzers understand + * code flow better. On compilers without noreturn support, this is defined to + * nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NORETURN __attribute__((noreturn)) + +/** + * A macro to tag a function as never-returning (for analysis purposes). + * + * This is almost identical to SDL_NORETURN, except functions marked with this + * _can_ actually return. The difference is that this isn't used for code + * generation, but rather static analyzers use this information to assume + * truths about program state and available code paths. Specifically, this tag + * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this + * tag behind the scenes. Generally, apps that don't understand the specific + * use-case for this tag should avoid using it directly. + * + * On compilers without analyzer_noreturn support, this is defined to nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) + + +/** + * A macro to signal that a case statement without a `break` is intentional. + * + * C compilers have gotten more aggressive about warning when a switch's + * `case` block does not end with a `break` or other flow control statement, + * flowing into the next case's code, as this is a common accident that leads + * to strange bugs. But sometimes falling through to the next case is the + * correct and desired behavior. This symbol lets an app communicate this + * intention to the compiler, so it doesn't generate a warning. + * + * It is used like this: + * + * ```c + * switch (x) { + * case 1: + * DoSomethingOnlyForOne(); + * SDL_FALLTHROUGH; // tell the compiler this was intentional. + * case 2: + * DoSomethingForOneAndTwo(); + * break; + * } + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FALLTHROUGH [[fallthrough]] + +/** + * A macro to tag a function's return value as critical. + * + * This is a hint to the compiler that a function's return value should not be + * ignored. + * + * If an NODISCARD function's return value is thrown away (the function is + * called as if it returns `void`), the compiler will issue a warning. + * + * While it's generally good practice to check return values for errors, often + * times legitimate programs do not for good reasons. Be careful about what + * functions are tagged as NODISCARD. It operates best when used on a function + * that's failure is surprising and catastrophic; a good example would be a + * program that checks the return values of all its file write function calls + * but not the call to close the file, which it assumes incorrectly never + * fails. + * + * Function callers that want to throw away a NODISCARD return value can call + * the function with a `(void)` cast, which informs the compiler the act is + * intentional. + * + * On compilers without nodiscard support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NODISCARD [[nodiscard]] + +/** + * A macro to tag a function as an allocator. + * + * This is a hint to the compiler that a function is an allocator, like + * malloc(), with certain rules. A description of how GCC treats this hint is + * here: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute + * + * On compilers without allocator tag support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) + +/** + * A macro to tag a function as returning a certain allocation. + * + * This is a hint to the compiler that a function allocates and returns a + * specific amount of memory based on one of its arguments. For example, the C + * runtime's malloc() function could use this macro with an argument of 1 + * (first argument to malloc is the size of the allocation). + * + * On compilers without alloc_size support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) + +/** + * A macro to tag a pointer variable, to help with pointer aliasing. + * + * A good explanation of the restrict keyword is here: + * + * https://en.wikipedia.org/wiki/Restrict + * + * On compilers without restrict support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_RESTRICT __restrict__ + +/** + * Check if the compiler supports a given builtin functionality. + * + * This allows preprocessor checks for things that otherwise might fail to + * compile. + * + * Supported by virtually all clang versions and more-recent GCCs. Use this + * instead of checking the clang version if possible. + * + * On compilers without has_builtin support, this is defined to 0 (always + * false). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAS_BUILTIN(x) __has_builtin(x) + +/* end of wiki documentation section. */ +#endif + +#ifndef SDL_HAS_BUILTIN +#ifdef __has_builtin +#define SDL_HAS_BUILTIN(x) __has_builtin(x) +#else +#define SDL_HAS_BUILTIN(x) 0 +#endif +#endif + #ifndef SDL_DEPRECATED # if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ # define SDL_DEPRECATED __attribute__((deprecated)) @@ -53,7 +312,7 @@ /* Some compilers use a special export keyword */ #ifndef SDL_DECLSPEC -# if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_CYGWIN) || defined(SDL_PLATFORM_GDK) +# if defined(SDL_PLATFORM_WINDOWS) # ifdef DLL_EXPORT # define SDL_DECLSPEC __declspec(dllexport) # else @@ -70,7 +329,7 @@ /* By default SDL uses the C calling convention */ #ifndef SDLCALL -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_GDK)) && !defined(__GNUC__) +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) #define SDLCALL __cdecl #else #define SDLCALL diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_bits.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_bits.h index 72be082..7435ce6 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_bits.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_bits.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -36,10 +36,6 @@ extern "C" { #endif -/** - * \file SDL_bits.h - */ - #if defined(__WATCOMC__) && defined(__386__) extern __inline int _SDL_bsr_watcom(Uint32); #pragma aux _SDL_bsr_watcom = \ @@ -65,7 +61,7 @@ extern __inline int _SDL_bsr_watcom(Uint32); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { @@ -82,10 +78,10 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) return -1; } return _SDL_bsr_watcom(x); -#elif defined(_MSC_VER) +#elif defined(_MSC_VER) && _MSC_VER >= 1400 unsigned long index; if (_BitScanReverse(&index, x)) { - return index; + return (int)index; } return -1; #else @@ -120,8 +116,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * Determine if a unsigned 32-bit value has exactly one bit set. * * If there are no bits set (`x` is zero), or more than one bit set, this - * returns SDL_FALSE. If any one bit is exclusively set, this returns - * SDL_TRUE. + * returns false. If any one bit is exclusively set, this returns true. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is @@ -129,18 +124,18 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine. - * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. + * \returns true if exactly one bit is set in `x`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_HasExactlyOneBitSet32(Uint32 x) +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_blendmode.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_blendmode.h index 76aa197..8f00cbc 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_blendmode.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_blendmode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,7 @@ * * Blend modes decide how two colors will mix together. There are both * standard modes for basic needs and a means to create custom modes, - * dictating what sort of math to do what on what color components. + * dictating what sort of math to do on what color components. */ #ifndef SDL_blendmode_h_ @@ -45,7 +45,7 @@ extern "C" { * * Additional values may be obtained from SDL_ComposeCustomBlendMode. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_ComposeCustomBlendMode */ @@ -64,7 +64,7 @@ typedef Uint32 SDL_BlendMode; * The blend operation used when combining source and destination pixel * components. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendOperation { @@ -83,7 +83,7 @@ typedef enum SDL_BlendOperation * operation. The comma-separated factors listed above are always applied in * the component order red, green, blue, and alpha. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendFactor { @@ -177,7 +177,9 @@ typedef enum SDL_BlendFactor * \returns an SDL_BlendMode that represents the chosen factors and * operations. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode * \sa SDL_GetRenderDrawBlendMode diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_camera.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_camera.h index 3d4c57e..c4d0596 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_camera.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_camera.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -28,13 +28,51 @@ * devices can be enumerated, queried, and opened. Once opened, it will * provide SDL_Surface objects as new frames of video come in. These surfaces * can be uploaded to an SDL_Texture or processed as pixels in memory. + * + * Several platforms will alert the user if an app tries to access a camera, + * and some will present a UI asking the user if your application should be + * allowed to obtain images at all, which they can deny. A successfully opened + * camera will not provide images until permission is granted. Applications, + * after opening a camera device, can see if they were granted access by + * either polling with the SDL_GetCameraPermissionState() function, or waiting + * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED + * event. Platforms that don't have any user approval process will report + * approval immediately. + * + * Note that SDL cameras only provide video as individual frames; they will + * not provide full-motion video encoded in a movie file format, although an + * app is free to encode the acquired frames into any format it likes. It also + * does not provide audio from the camera hardware through this API; not only + * do many webcams not have microphones at all, many people--from streamers to + * people on Zoom calls--will want to use a separate microphone regardless of + * the camera. In any case, recorded audio will be available through SDL's + * audio API no matter what hardware provides the microphone. + * + * ## Camera gotchas + * + * Consumer-level camera hardware tends to take a little while to warm up, + * once the device has been opened. Generally most camera apps have some sort + * of UI to take a picture (a button to snap a pic while a preview is showing, + * some sort of multi-second countdown for the user to pose, like a photo + * booth), which puts control in the users' hands, or they are intended to + * stay on for long times (Pokemon Go, etc). + * + * It's not uncommon that a newly-opened camera will provide a couple of + * completely black frames, maybe followed by some under-exposed images. If + * taking a single frame automatically, or recording video from a camera's + * input without the user initiating it from a preview, it could be wise to + * drop the first several frames (if not the first several _seconds_ worth of + * frames!) before using images from a camera. */ #ifndef SDL_camera_h_ #define SDL_camera_h_ +#include #include -#include +#include +#include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -50,7 +88,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -59,7 +97,7 @@ typedef Uint32 SDL_CameraID; /** * The opaque structure used to identify an opened SDL camera. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Camera SDL_Camera; @@ -69,7 +107,7 @@ typedef struct SDL_Camera SDL_Camera; * Cameras often support multiple formats; each one will be encapsulated in * this struct. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetCameraSupportedFormats * \sa SDL_GetCameraFormat @@ -87,7 +125,7 @@ typedef struct SDL_CameraSpec /** * The position of camera in relation to system device. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCameraPosition */ @@ -116,7 +154,7 @@ typedef enum SDL_CameraPosition * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameraDriver */ @@ -140,7 +178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumCameraDrivers */ @@ -158,7 +196,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); @@ -173,7 +211,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -211,7 +249,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_OpenCamera @@ -227,7 +265,7 @@ extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -246,7 +284,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -265,7 +303,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * You can call SDL_GetCameraFormat() to get the actual data format if passing * a NULL spec here. You can see the exact specs a device can support without - * conversion with SDL_GetCameraSupportedSpecs(). + * conversion with SDL_GetCameraSupportedFormats(). * * SDL will not attempt to emulate framerate; it will try to set the hardware * to the rate closest to the requested speed, but it won't attempt to limit @@ -278,10 +316,11 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * the camera, and they can choose Yes or No at that point. Until they do, the * camera will not be usable. The app should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On - * platforms that don't require explicit user approval (and perhaps in places - * where the user previously permitted access), the approval event might come - * immediately, but it might come seconds, minutes, or hours later! + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. On platforms that don't require explicit user approval (and + * perhaps in places where the user previously permitted access), the approval + * event might come immediately, but it might come seconds, minutes, or hours + * later! * * \param instance_id the camera device instance ID. * \param spec the desired format for data the device will provide. Can be @@ -291,7 +330,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_GetCameraFormat @@ -324,7 +363,7 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera * \sa SDL_CloseCamera @@ -340,7 +379,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -355,7 +394,7 @@ extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera); @@ -366,23 +405,24 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * be converting to this format behind the scenes. * * If the system is waiting for the user to approve access to the camera, as - * some platforms require, this will return SDL_FALSE, but this isn't - * necessarily a fatal error; you should either wait for an + * some platforms require, this will return false, but this isn't necessarily + * a fatal error; you should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. * * \param camera opened camera device. * \param spec the SDL_CameraSpec to be initialized by this function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); /** * Acquire a frame. @@ -404,14 +444,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * After use, the frame should be released with SDL_ReleaseCameraFrame(). If * you don't do this, the system may stop providing more video! * - * Do not call SDL_FreeSurface() on the returned surface! It must be given + * Do not call SDL_DestroySurface() on the returned surface! It must be given * back to the camera subsystem with SDL_ReleaseCameraFrame! * * If the system is waiting for the user to approve access to the camera, as * some platforms require, this will return NULL (no frames available); you * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or - * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() - * occasionally until it returns non-zero. + * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll + * SDL_GetCameraPermissionState() occasionally until it returns non-zero. * * \param camera opened camera device. * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on @@ -421,7 +461,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReleaseCameraFrame */ @@ -449,7 +489,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireCameraFrame */ @@ -464,9 +504,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_ * \threadsafety It is safe to call this function from any thread, but no * thread may reference `device` once this function is called. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_OpenCameraWithSpec * \sa SDL_OpenCamera */ extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_clipboard.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_clipboard.h index 4d4ae32..0d3cbb4 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_clipboard.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_clipboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,51 @@ * from other processes and publishing information of its own. * * This is not just text! SDL apps can access and publish data by mimetype. + * + * ## Basic use (text) + * + * Obtaining and publishing simple text to the system clipboard is as easy as + * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively. + * These deal with C strings in UTF-8 encoding. Data transmission and encoding + * conversion is completely managed by SDL. + * + * ## Clipboard callbacks (data other than text) + * + * Things get more complicated when the clipboard contains something other + * than text. Not only can the system clipboard contain data of any type, in + * some cases it can contain the same data in different formats! For example, + * an image painting app might let the user copy a graphic to the clipboard, + * and offers it in .BMP, .JPG, or .PNG format for other apps to consume. + * + * Obtaining clipboard data ("pasting") like this is a matter of calling + * SDL_GetClipboardData() and telling it the mimetype of the data you want. + * But how does one know if that format is available? SDL_HasClipboardData() + * can report if a specific mimetype is offered, and + * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes + * available, so the app can decide what to do with the data and what formats + * it can support. + * + * Setting the clipboard ("copying") to arbitrary data is done with + * SDL_SetClipboardData. The app does not provide the data in this call, but + * rather the mimetypes it is willing to provide and a callback function. + * During the callback, the app will generate the data. This allows massive + * data sets to be provided to the clipboard, without any data being copied + * before it is explicitly requested. More specifically, it allows an app to + * offer data in multiple formats without providing a copy of all of them + * upfront. If the app has an image that it could provide in PNG or JPG + * format, it doesn't have to encode it to either of those unless and until + * something tries to paste it. + * + * ## Primary Selection + * + * The X11 and Wayland video targets have a concept of the "primary selection" + * in addition to the usual clipboard. This is generally highlighted (but not + * explicitly copied) text from various apps. SDL offers APIs for this through + * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers + * these APIs on platforms without this concept, too, but only so far that it + * will keep a copy of a string that the app sets for later retrieval; the + * operating system will not ever attempt to change the string externally if + * it doesn't support a primary selection. */ #ifndef SDL_clipboard_h_ @@ -46,27 +91,31 @@ extern "C" { * Put UTF-8 text into the clipboard. * * \param text the text to store in the clipboard. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_HasClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); /** * Get UTF-8 text from the clipboard. * - * This functions returns empty string if there was not enough memory left for - * a copy of the clipboard's content. + * This functions returns an empty string if there was 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 * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardText * \sa SDL_SetClipboardText @@ -76,40 +125,46 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); /** * Query whether the clipboard exists and contains a non-empty text string. * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * \returns true if the clipboard has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_SetClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * * \param text the text to store in the primary selection. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_HasPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPrimarySelectionText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); /** * Get UTF-8 text from the primary selection. * - * This functions returns empty string if there was not enough memory left for - * a copy of the primary selection's content. + * This functions returns an empty string if there was 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 * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasPrimarySelectionText * \sa SDL_SetPrimarySelectionText @@ -120,15 +175,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * Query whether the primary selection exists and contains a non-empty text * string. * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. + * \returns true if the primary selection has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_SetPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); /** * Callback function that will be called when data for the specified mime-type @@ -148,7 +204,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); * breakage in receiving applications. 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.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -160,7 +216,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c * * \param userdata a pointer to provided user data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -170,13 +226,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * Offer clipboard data to the OS. * * Tell the operating system that the application is offering clipboard data - * for each of the proivded mime-types. Once another application requests the - * data the callback function will be called allowing it to generate and + * for each of the provided mime-types. Once another application requests the + * data the callback function will be called, allowing it to generate and * 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 - * document) + * document). * * \param callback a function pointer to the function that provides the * clipboard data. @@ -185,28 +241,32 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \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 num_mime_types the number of mime-types in the mime_types list. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearClipboardData * \sa SDL_GetClipboardData * \sa SDL_HasClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** * Clear the clipboard data. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); /** * Get the data from clipboard for a given mime type. @@ -220,7 +280,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); * for more information. This should be freed with SDL_free() when it * is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardData * \sa SDL_SetClipboardData @@ -231,15 +293,34 @@ 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 SDL_TRUE if there exists data in clipboard for the provided mime - * type, SDL_FALSE if it does not. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData * \sa SDL_GetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \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 + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_close_code.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_close_code.h index fa4d3d1..da1dea7 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_close_code.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_close_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -21,7 +21,10 @@ /* * This file reverses the effects of SDL_begin_code.h and should be included - * after you finish any function and structure declarations in your headers + * after you finish any function and structure declarations in your headers. + * + * SDL's headers use this; applications generally should not include this + * header directly. */ #ifndef SDL_begin_code_h diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_copying.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_copying.h index dcbdcea..747bd35 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_copying.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_copying.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_cpuinfo.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_cpuinfo.h index e7ced26..1745bd9 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_cpuinfo.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_cpuinfo.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,6 +29,12 @@ * These functions are largely concerned with reporting if the system has * access to various SIMD instruction sets, but also has other important info * to share, such as system RAM size and number of logical CPU cores. + * + * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are + * available on all platforms, even if they don't make sense (an ARM processor + * will never have SSE and an x86 processor will never have NEON, for example, + * but these functions still exist and will simply return false in these + * cases). */ #ifndef SDL_cpuinfo_h_ @@ -49,20 +55,22 @@ extern "C" { * processors have a 128 byte cache line. We use the larger value to be * generally safe. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CACHELINE_SIZE 128 /** - * Get the number of CPU cores available. + * Get the number of logical CPU cores available. * * \returns the total number of logical CPU cores. On CPUs that include * technologies such as hyperthreading, the number of logical cores * may be more than the number of physical cores. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); /** * Determine the L1 cache line size of the CPU. @@ -72,7 +80,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); * * \returns the L1 cache line size of the CPU, in bytes. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); @@ -82,144 +92,164 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * This always returns false on CPUs that aren't using PowerPC instruction * sets. * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. + * \returns true if the CPU has AltiVec features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); /** * Determine whether the CPU has MMX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. + * \returns true if the CPU has MMX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); /** * Determine whether the CPU has SSE features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. + * \returns true if the CPU has SSE features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); /** * Determine whether the CPU has SSE2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); /** * Determine whether the CPU has SSE3 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. + * \returns true if the CPU has SSE3 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); /** * Determine whether the CPU has SSE4.1 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.1 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); /** * Determine whether the CPU has SSE4.2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); /** * Determine whether the CPU has AVX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. + * \returns true if the CPU has AVX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX2 * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); /** * Determine whether the CPU has AVX2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. + * \returns true if the CPU has AVX2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); /** * Determine whether the CPU has AVX-512F (foundation) features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. + * \returns true if the CPU has AVX-512F features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX2 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); /** * Determine whether the CPU has ARM SIMD (ARMv6) features. @@ -228,24 +258,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. + * \returns true if the CPU has ARM SIMD features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasNEON */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); /** * Determine whether the CPU has NEON (ARM SIMD) features. * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. + * \returns true if the CPU has ARM NEON features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); /** * Determine whether the CPU has LSX (LOONGARCH SIMD) features. @@ -253,12 +287,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LSX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); /** * Determine whether the CPU has LASX (LOONGARCH SIMD) features. @@ -266,19 +301,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LASX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); /** * Get the amount of RAM configured in the system. * * \returns the amount of RAM configured in the system in MiB. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); @@ -297,7 +335,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); * \returns the alignment in bytes needed for available, known SIMD * instructions. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc * \sa SDL_aligned_free diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_dialog.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_dialog.h index 8a198a8..460038f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_dialog.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_dialog.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,12 +23,23 @@ * # CategoryDialog * * File dialog support. + * + * SDL offers file dialogs, to let users select files with native GUI + * interfaces. There are "open" dialogs, "save" dialogs, and folder selection + * dialogs. The app can control some details, such as filtering to specific + * files, or whether multiple files can be selected by the user. + * + * Note that launching a file dialog is a non-blocking operation; control + * returns to the app immediately, and a callback is called later (possibly in + * another thread) when the user makes a choice. */ #ifndef SDL_dialog_h_ #define SDL_dialog_h_ +#include #include +#include #include #include @@ -48,12 +59,13 @@ extern "C" { * hyphens, underscores and periods. Alternatively, the whole string can be a * single asterisk ("*"), which serves as an "All files" filter. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef struct SDL_DialogFileFilter { @@ -75,31 +87,34 @@ typedef struct SDL_DialogFileFilter * is a null-terminated list of pointers to C strings, each containing a * path. * - * The filelist argument does not need to be freed; it will automatically be - * freed when the callback returns. + * The filelist argument should not be freed; it will automatically be freed + * when the callback returns. * * The filter argument is the index of the filter that was selected, or -1 if * no filter was selected or if the platform or method doesn't support * fetching the selected filter. * + * In Android, the `filelist` are `content://` URIs. They should be opened + * using SDL_IOFromFile() with appropriate modes. This applies both to open + * and save file dialog. + * * \param userdata an app-provided pointer, for the callback's use. * \param filelist the file(s) chosen by the user. * \param filter index of the selected filter. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter); /** * Displays a dialog that lets the user select a file on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -117,47 +132,41 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); /** * Displays a dialog that lets the user choose a new or existing file on their * filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -174,44 +183,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); /** * Displays a dialog that lets the user select a folder on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -229,31 +232,105 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is always -1 for SDL_ShowOpenFolderDialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \param window the window that the dialog should be modal for, may be NULL. * Not all platforms support this option. - * \param default_location the default folder or file to start the dialog at. - * May be NULL. Not all platforms support this option. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); + +/** + * Various types of file dialogs. + * + * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of + * dialog to present to the user. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ShowFileDialogWithProperties + */ +typedef enum SDL_FileDialogType +{ + SDL_FILEDIALOG_OPENFILE, + SDL_FILEDIALOG_SAVEFILE, + SDL_FILEDIALOG_OPENFOLDER +} SDL_FileDialogType; + +/** + * Create and launch a file dialog with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of + * SDL_DialogFileFilter structs, which will be used as filters for + * file-based selections. Ignored if the dialog is an "Open Folder" dialog. + * If non-NULL, the array of filters must remain valid at least until the + * callback is invoked. + * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the + * array of filters, if it exists. + * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should + * be modal for. + * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to + * start the dialog at. + * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select + * more than one entry. + * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. + * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button + * should have. + * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button + * should have. + * + * Note that each platform may or may not support any of the properties. + * + * \param type the type of file dialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param props the properties to use. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FileDialogType + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); + +#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" +#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" +#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" +#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" +#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" +#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" +#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" +#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -261,4 +338,4 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback #endif #include -#endif /* SDL_joystick_h_ */ +#endif /* SDL_dialog_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_egl.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_egl.h index cc557d6..65d4e96 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_egl.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_egl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_endian.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_endian.h index cb3d7f3..a34e9d4 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_endian.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_endian.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,20 @@ /** * # CategoryEndian * - * Functions for reading and writing endian-specific values. + * Functions converting endian-specific values to different byte orders. + * + * These functions either unconditionally swap byte order (SDL_Swap16, + * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's + * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, + * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the + * latter case, the functionality is provided by macros that become no-ops if + * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE + * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC + * processor (bigendian), the macros behavior is reversed. + * + * The swap routines are inline functions, and attempt to use compiler + * intrinsics, inline assembly, and other magic to make byteswapping + * efficient. */ #ifndef SDL_endian_h_ @@ -51,12 +64,71 @@ _m_prefetch(void *__P) * \name The two types of endianness */ /* @{ */ + + +/** + * A value to represent littleendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_LIL_ENDIAN + * SDL_Log("This system is littleendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_BIG_ENDIAN + */ #define SDL_LIL_ENDIAN 1234 + +/** + * A value to represent bigendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_LIL_ENDIAN + */ #define SDL_BIG_ENDIAN 4321 + /* @} */ #ifndef SDL_BYTEORDER -#ifdef SDL_PLATFORM_LINUX +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's byte order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +#elif defined(SDL_PLATFORM_LINUX) #include #define SDL_BYTEORDER __BYTE_ORDER #elif defined(SDL_PLATFORM_SOLARIS) @@ -97,8 +169,29 @@ _m_prefetch(void *__P) #endif /* !SDL_BYTEORDER */ #ifndef SDL_FLOATWORDORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's floating point word order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN + * SDL_Log("This system's floats are bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN /* predefs from newer gcc versions: */ -#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) #if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) #define SDL_FLOATWORDORDER SDL_LIL_ENDIAN #elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) @@ -125,10 +218,6 @@ _m_prefetch(void *__P) extern "C" { #endif -/** - * \file SDL_endian.h - */ - /* various modern compilers may have builtin swap */ #if defined(__GNUC__) || defined(__clang__) # define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \ @@ -148,6 +237,7 @@ extern "C" { #endif /* Byte swap 16-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP16 #define SDL_Swap16(x) __builtin_bswap16(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -191,8 +281,10 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); } #endif +#endif /* Byte swap 32-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP32 #define SDL_Swap32(x) __builtin_bswap32(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -239,8 +331,10 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) ((x >> 8) & 0x0000FF00) | (x >> 24))); } #endif +#endif /* Byte swap 64-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP64 #define SDL_Swap64(x) __builtin_bswap64(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -290,7 +384,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) return (x); } #endif - +#endif /** * Byte-swap a floating point number. @@ -309,7 +403,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { @@ -348,7 +442,7 @@ SDL_FORCE_INLINE float SDL_SwapFloat(float x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } @@ -369,7 +463,7 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } @@ -390,7 +484,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } @@ -404,7 +498,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16LE(x) SwapOnlyIfNecessary(x) @@ -418,7 +514,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32LE(x) SwapOnlyIfNecessary(x) @@ -432,7 +530,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64LE(x) SwapOnlyIfNecessary(x) @@ -446,7 +546,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x) @@ -460,7 +562,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16BE(x) SwapOnlyIfNecessary(x) @@ -474,7 +578,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32BE(x) SwapOnlyIfNecessary(x) @@ -488,7 +594,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64BE(x) SwapOnlyIfNecessary(x) @@ -502,7 +610,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_error.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_error.h index a98823f..934967c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_error.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_error.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,26 @@ * # CategoryError * * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. */ #ifndef SDL_error_h_ @@ -44,8 +64,8 @@ extern "C" { * * Calling this function will replace any previous error message that was set. * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: * * ```c * if (error_code) { @@ -56,25 +76,49 @@ extern "C" { * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if * any. - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_GetError + * \sa SDL_SetErrorV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * \param fmt a printf()-style message format string. + * \param ap a variable argument list. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1); /** * Set an error indicating that memory allocation failed. * * This function does not do any memory allocation. * - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); /** * Retrieve a message about the last error that occurred on the current @@ -104,7 +148,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); * or an empty string if there hasn't been an error message set since * the last call to SDL_ClearError(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_SetError @@ -114,14 +160,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); /** * Clear any previous error message for this thread. * - * \returns SDL_TRUE. + * \returns true. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetError * \sa SDL_SetError */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); /** * \name Internal error functions @@ -130,8 +178,43 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); * Private error reporting function - used internally. */ /* @{ */ + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_Unsupported() SDL_SetError("That operation is not supported") + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * A common usage pattern inside SDL is this: + * + * ```c + * bool MyFunction(const char *str) { + * if (!str) { + * return SDL_InvalidParamError("str"); // returns false. + * } + * DoSomething(str); + * return true; + * } + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + /* @} *//* Internal error functions */ /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_events.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_events.h index fbe2bb0..1323e9f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_events.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_events.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,22 +23,50 @@ * # CategoryEvents * * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. */ #ifndef SDL_events_h_ #define SDL_events_h_ +#include #include +#include #include #include #include #include +#include #include #include -#include +#include +#include +#include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,29 +76,10 @@ extern "C" { /* General keyboard/mouse/pen state definitions */ -/** - * A value that signifies a button is no longer pressed. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_PRESSED - */ -#define SDL_RELEASED 0 - -/** - * A value that signifies a button has been pressed down. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_RELEASED - */ -#define SDL_PRESSED 1 - - /** * The types of events that can be delivered. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_EventType { @@ -148,7 +157,7 @@ typedef enum SDL_EventType SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */ SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */ SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled - in an event watcher, the window handle is still valid and can still be used to retrieve any userdata + in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid */ SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ @@ -203,6 +212,7 @@ typedef enum SDL_EventType SDL_EVENT_FINGER_DOWN = 0x700, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, + SDL_EVENT_FINGER_CANCELED, /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ @@ -243,6 +253,13 @@ typedef enum SDL_EventType /* Render events */ SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ + SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + SDL_EVENT_PRIVATE0 = 0x4000, + SDL_EVENT_PRIVATE1, + SDL_EVENT_PRIVATE2, + SDL_EVENT_PRIVATE3, /* Internal events */ SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ @@ -265,7 +282,7 @@ typedef enum SDL_EventType /** * Fields shared by every event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CommonEvent { @@ -277,7 +294,7 @@ typedef struct SDL_CommonEvent /** * Display state change event data (event.display.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DisplayEvent { @@ -292,7 +309,7 @@ typedef struct SDL_DisplayEvent /** * Window state change event data (event.window.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_WindowEvent { @@ -307,7 +324,7 @@ typedef struct SDL_WindowEvent /** * Keyboard device event structure (event.kdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_KeyboardDeviceEvent { @@ -326,7 +343,7 @@ typedef struct SDL_KeyboardDeviceEvent * event scancode and modifiers directly from the keyboard layout, bypassing * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_HINT_KEYCODE_OPTIONS @@ -342,8 +359,8 @@ typedef struct SDL_KeyboardEvent SDL_Keycode key; /**< SDL virtual key code */ SDL_Keymod mod; /**< current key modifiers */ Uint16 raw; /**< The platform dependent scancode for this event */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ } SDL_KeyboardEvent; /** @@ -353,7 +370,7 @@ typedef struct SDL_KeyboardEvent * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingEvent { @@ -369,7 +386,7 @@ typedef struct SDL_TextEditingEvent /** * Keyboard IME candidates event structure (event.edit_candidates.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingCandidatesEvent { @@ -380,7 +397,10 @@ typedef struct SDL_TextEditingCandidatesEvent const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ Sint32 num_candidates; /**< The number of strings in `candidates` */ Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ - SDL_bool horizontal; /**< SDL_TRUE if the list is horizontal, SDL_FALSE if it's vertical */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_TextEditingCandidatesEvent; /** @@ -389,7 +409,7 @@ typedef struct SDL_TextEditingCandidatesEvent * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput @@ -406,7 +426,7 @@ typedef struct SDL_TextInputEvent /** * Mouse device event structure (event.mdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseDeviceEvent { @@ -419,7 +439,7 @@ typedef struct SDL_MouseDeviceEvent /** * Mouse motion event structure (event.motion.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseMotionEvent { @@ -427,7 +447,7 @@ typedef struct SDL_MouseMotionEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id or SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ SDL_MouseButtonFlags state; /**< The current button state */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ @@ -438,7 +458,7 @@ typedef struct SDL_MouseMotionEvent /** * Mouse button event structure (event.button.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseButtonEvent { @@ -446,9 +466,9 @@ typedef struct SDL_MouseButtonEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding; float x; /**< X coordinate, relative to window */ @@ -458,7 +478,7 @@ typedef struct SDL_MouseButtonEvent /** * Mouse wheel event structure (event.wheel.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseWheelEvent { @@ -466,7 +486,7 @@ typedef struct SDL_MouseWheelEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */ float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ @@ -477,7 +497,7 @@ typedef struct SDL_MouseWheelEvent /** * Joystick axis motion event structure (event.jaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyAxisEvent { @@ -496,7 +516,7 @@ typedef struct SDL_JoyAxisEvent /** * Joystick trackball motion event structure (event.jball.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBallEvent { @@ -515,7 +535,7 @@ typedef struct SDL_JoyBallEvent /** * Joystick hat position change event structure (event.jhat.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyHatEvent { @@ -538,7 +558,7 @@ typedef struct SDL_JoyHatEvent /** * Joystick button event structure (event.jbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyButtonEvent { @@ -547,7 +567,7 @@ typedef struct SDL_JoyButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; @@ -555,7 +575,12 @@ typedef struct SDL_JoyButtonEvent /** * Joystick device event structure (event.jdevice.*) * - * \since This struct is available since SDL 3.0.0. + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GamepadDeviceEvent */ typedef struct SDL_JoyDeviceEvent { @@ -566,9 +591,9 @@ typedef struct SDL_JoyDeviceEvent } SDL_JoyDeviceEvent; /** - * Joysick battery level change event structure (event.jbattery.*) + * Joystick battery level change event structure (event.jbattery.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBatteryEvent { @@ -583,7 +608,7 @@ typedef struct SDL_JoyBatteryEvent /** * Gamepad axis motion event structure (event.gaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadAxisEvent { @@ -603,7 +628,7 @@ typedef struct SDL_GamepadAxisEvent /** * Gamepad button event structure (event.gbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadButtonEvent { @@ -612,7 +637,7 @@ typedef struct SDL_GamepadButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_GamepadButtonEvent; @@ -621,7 +646,16 @@ typedef struct SDL_GamepadButtonEvent /** * Gamepad device event structure (event.gdevice.*) * - * \since This struct is available since SDL 3.0.0. + * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent + * and an SDL_GamepadDeviceEvent. + * + * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged + * in during SDL_Init() and are recognized as gamepads. It will also send + * events for joysticks that get gamepad mappings at runtime. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_JoyDeviceEvent */ typedef struct SDL_GamepadDeviceEvent { @@ -634,7 +668,7 @@ typedef struct SDL_GamepadDeviceEvent /** * Gamepad touchpad event structure (event.gtouchpad.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadTouchpadEvent { @@ -652,7 +686,7 @@ typedef struct SDL_GamepadTouchpadEvent /** * Gamepad sensor event structure (event.gsensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadSensorEvent { @@ -668,7 +702,7 @@ typedef struct SDL_GamepadSensorEvent /** * Audio device event structure (event.adevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AudioDeviceEvent { @@ -676,7 +710,7 @@ typedef struct SDL_AudioDeviceEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ - Uint8 recording; /**< zero if a playback device, non-zero if a recording device. */ + bool recording; /**< false if a playback device, true if a recording device. */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -685,7 +719,7 @@ typedef struct SDL_AudioDeviceEvent /** * Camera device event structure (event.cdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CameraDeviceEvent { @@ -695,14 +729,43 @@ typedef struct SDL_CameraDeviceEvent SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ } SDL_CameraDeviceEvent; + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RenderEvent +{ + SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window containing the renderer in question. */ +} SDL_RenderEvent; + + /** * Touch finger event structure (event.tfinger.*) * - * \since This struct is available since SDL 3.0.0. + * Coordinates in this event are normalized. `x` and `y` are normalized to a + * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top + * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are + * normalized in the ranges of -1.0f (traversed all the way from the bottom or + * right to all the way up or left) to 1.0f (traversed all the way from the + * top or left to all the way down or right). + * + * Note that while the coordinates are _normalized_, they are not _clamped_, + * which means in some circumstances you can get a value outside of this + * range. For example, a renderer using logical presentation might give a + * negative value when the touch is in the letterboxing. Some platforms might + * report a touch outside of the window, which will also be outside of the + * range. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TouchFingerEvent { - SDL_EventType type; /**< SDL_EVENT_FINGER_MOTION or SDL_EVENT_FINGER_DOWN or SDL_EVENT_FINGER_UP */ + SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_TouchID touchID; /**< The touch device id */ @@ -728,14 +791,14 @@ typedef struct SDL_TouchFingerEvent * is there." The pen touching and lifting off from the tablet while not * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenProximityEvent { SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ } SDL_PenProximityEvent; @@ -748,18 +811,18 @@ typedef struct SDL_PenProximityEvent * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when * dealing with pen motion. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenMotionEvent { SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ } SDL_PenMotionEvent; /** @@ -768,7 +831,7 @@ typedef struct SDL_PenMotionEvent * These events come when a pen touches a surface (a tablet, etc), or lifts * off from one. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenTouchEvent { @@ -778,10 +841,10 @@ typedef struct SDL_PenTouchEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ - Uint8 eraser; /**< Non-zero if eraser end is used (not all pens support this). */ - Uint8 state; /**< SDL_PRESSED (pen is touching) or SDL_RELEASED (pen is lifted off) */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ } SDL_PenTouchEvent; /** @@ -790,7 +853,7 @@ typedef struct SDL_PenTouchEvent * This is for buttons on the pen itself that the user might click. The pen * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenButtonEvent { @@ -800,10 +863,10 @@ typedef struct SDL_PenButtonEvent SDL_WindowID windowID; /**< The window with mouse focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ Uint8 button; /**< The pen button index (first button is 1). */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ } SDL_PenButtonEvent; /** @@ -812,7 +875,7 @@ typedef struct SDL_PenButtonEvent * You might get some of these events even if the pen isn't touching the * tablet. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenAxisEvent { @@ -822,8 +885,8 @@ typedef struct SDL_PenAxisEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ SDL_PenAxis axis; /**< Axis that has changed */ float value; /**< New value of axis */ } SDL_PenAxisEvent; @@ -832,7 +895,7 @@ typedef struct SDL_PenAxisEvent * An event used to drop text or request a file open by the system * (event.drop.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DropEvent { @@ -850,19 +913,22 @@ typedef struct SDL_DropEvent * An event triggered when the clipboard contents have changed * (event.clipboard.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_ClipboardEvent { SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + bool owner; /**< are we owning the clipboard (internal update) */ + Sint32 num_mime_types; /**< number of mime types */ + const char **mime_types; /**< current mime types */ } SDL_ClipboardEvent; /** * Sensor event structure (event.sensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_SensorEvent { @@ -877,7 +943,7 @@ typedef struct SDL_SensorEvent /** * The "quit requested" event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_QuitEvent { @@ -895,7 +961,7 @@ typedef struct SDL_QuitEvent * the programmer; the only requirement is that '''type''' is a value obtained * from SDL_RegisterEvents(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_UserEvent { @@ -912,7 +978,10 @@ typedef struct SDL_UserEvent /** * The structure for all events in SDL. * - * \since This struct is available since SDL 3.0.0. + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. + * + * \since This struct is available since SDL 3.2.0. */ typedef union SDL_Event { @@ -951,6 +1020,7 @@ typedef union SDL_Event SDL_PenMotionEvent pmotion; /**< Pen motion event data */ SDL_PenButtonEvent pbutton; /**< Pen button event data */ SDL_PenAxisEvent paxis; /**< Pen axis event data */ + SDL_RenderEvent render; /**< Render event data */ SDL_DropEvent drop; /**< Drag and drop event data */ SDL_ClipboardEvent clipboard; /**< Clipboard event data */ @@ -981,10 +1051,6 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * * This function updates the event queue and internal input device state. * - * **WARNING**: This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider only doing those - * things on the main thread in any case. - * * SDL_PumpEvents() gathers all the pending input information from devices and * places it in the event queue. Without calls to SDL_PumpEvents() no events * would ever be placed on the queue. Often the need for calls to @@ -993,7 +1059,9 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * polling or waiting for events (e.g. you are filtering them), then you must * call SDL_PumpEvents() to force an event queue update. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent @@ -1001,11 +1069,17 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_EventAction { - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ } SDL_EventAction; /** @@ -1017,7 +1091,9 @@ typedef enum SDL_EventAction * event queue. * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. + * caller and will _not_ be removed from the queue. If you pass NULL for + * `events`, then `numevents` is ignored and the total number of matching + * events will be returned. * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the * caller and will be removed from the queue. @@ -1026,8 +1102,6 @@ typedef enum SDL_EventAction * Otherwise, the events may not be ready to be filtered when you call * SDL_PeepEvents(). * - * This function is thread-safe. - * * \param events destination buffer for the retrieved events, may be NULL to * leave the events in the queue and return the number of events * that would have been stored. @@ -1042,7 +1116,9 @@ typedef enum SDL_EventAction * \returns the number of events actually stored or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PumpEvents @@ -1058,14 +1134,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, * instead. * * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); /** @@ -1077,14 +1155,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); /** * Clear events of a specific type from the event queue. @@ -1106,7 +1186,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp * * \param type the type of event to be cleared; see SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvents */ @@ -1131,7 +1213,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * \param maxType the high end of event type to be cleared, inclusive; see * SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvent */ @@ -1171,16 +1255,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * * \param event the SDL_Event structure to be filled with the next event from * the queue, or NULL. - * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none - * available. + * \returns true if this got an event or false if there are none available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent * \sa SDL_WaitEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); /** * Wait indefinitely for the next available event. @@ -1193,16 +1278,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * * \param event the SDL_Event structure to be filled in with the next event * from the queue, or NULL. - * \returns SDL_TRUE on success or SDL_FALSE if there was an error while - * waiting for events; call SDL_GetError() for more information. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); /** * Wait until the specified timeout (in milliseconds) for the next available @@ -1221,16 +1308,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * from the queue, or NULL. * \param timeoutMS the maximum number of milliseconds to wait for the next * available event. - * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed - * without any events available. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEvent */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); /** * Add an event to the event queue. @@ -1244,8 +1333,6 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * Note: Pushing device input events onto the queue doesn't modify the state * of the device within SDL. * - * This function is thread-safe, and can be called from other threads safely. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter but events added with SDL_PeepEvents() do not. * @@ -1254,17 +1341,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * its own custom event types. * * \param event the SDL_Event to be added to the queue. - * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on - * failure; call SDL_GetError() for more information. A common reason - * for error is the event queue being full. + * \returns true on success, false if the event was filtered or on failure; + * call SDL_GetError() for more information. A common reason for + * error is the event queue being full. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PeepEvents * \sa SDL_PollEvent * \sa SDL_RegisterEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); /** * A function pointer used for callbacks that watch the event queue. @@ -1272,29 +1361,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * SDL_AddEventWatch, etc. * \param event the event that triggered the callback. - * \returns SDL_TRUE to permit event to be added to the queue, and SDL_FALSE - * to disallow it. When used with SDL_AddEventWatch, the return value - * is ignored. + * \returns true to permit event to be added to the queue, and false to + * disallow it. When used with SDL_AddEventWatch, the return value is + * ignored. * * \threadsafety SDL may call this callback at any time from any thread; the * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetEventFilter * \sa SDL_AddEventWatch */ -typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. * - * If the filter function returns SDL_TRUE when called, then the event will be - * added to the internal queue. If it returns SDL_FALSE, then the event will - * be dropped from the queue, but the internal state will still be updated. - * This allows selective filtering of dynamically arriving events. + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. + * + * If the filter function returns true when called, then the event will be + * added to the internal queue. If it returns false, then the event will be + * dropped from the queue, but the internal state will still be updated. This + * allows selective filtering of dynamically arriving events. * * **WARNING**: Be very careful of what you do in the event filter function, * as it may run in a different thread! @@ -1303,17 +1395,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. @@ -1321,11 +1405,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \threadsafety SDL may call the filter callback at any time from any thread; - * the application is responsible for locking resources the - * callback touches that need to be protected. + * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch * \sa SDL_SetEventEnabled @@ -1344,13 +1426,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void * \param filter the current callback function will be stored here. * \param userdata the pointer that is passed to the current event filter will * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. + * \returns true on success or false if there is no event filter set. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); /** * Add a callback to be triggered when an event is added to the event queue. @@ -1372,17 +1456,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, * * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); /** * Remove an event watch callback added with SDL_AddEventWatch(). @@ -1393,7 +1477,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, v * \param filter the function originally passed to SDL_AddEventWatch(). * \param userdata the pointer originally passed to SDL_AddEventWatch(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -1401,7 +1487,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo /** * Run a specific filter function on the current event queue, removing any - * events for which the filter returns SDL_FALSE. + * events for which the filter returns false. * * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), * this function does not change the filter permanently, it only uses the @@ -1410,7 +1496,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo * \param filter the SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetEventFilter * \sa SDL_SetEventFilter @@ -1423,23 +1511,27 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void * * \param type the type of event; see SDL_EventType for details. * \param enabled whether to process the event or not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EventEnabled */ -extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); /** * Query the state of processing events by type. * * \param type the type of event; see SDL_EventType for details. - * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. + * \returns true if the event is being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); /** * Allocate a set of user-defined events, and return the beginning event @@ -1449,7 +1541,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); * \returns the beginning event number, or 0 if numevents is invalid or if * there are not enough user-defined events left. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent */ @@ -1461,7 +1555,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); * \param event an event containing a `windowID`. * \returns the associated window on success or NULL if there is none. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_filesystem.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_filesystem.h index 5faa244..af3ca27 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_filesystem.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_filesystem.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,23 @@ /** * # CategoryFilesystem * - * SDL Filesystem API. + * SDL offers an API for examining and manipulating the system's filesystem. + * This covers most things one would need to do with directories, except for + * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) + * and [CategoryAsyncIO](CategoryAsyncIO) instead). + * + * There are functions to answer necessary path questions: + * + * - Where is my app's data? SDL_GetBasePath(). + * - Where can I safely write files? SDL_GetPrefPath(). + * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder(). + * - What is this thing at this location? SDL_GetPathInfo(). + * - What items live in this folder? SDL_EnumerateDirectory(). + * - What items live in this folder by wildcard? SDL_GlobDirectory(). + * - What is my current working directory? SDL_GetCurrentDirectory(). + * + * SDL also offers functions to manipulate the directory tree: renaming, + * removing, copying files. */ #ifndef SDL_filesystem_h_ @@ -73,7 +89,7 @@ extern "C" { * doesn't implement this functionality, call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrefPath */ @@ -128,7 +144,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); * etc.). This should be freed with SDL_free() when it is no longer * needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBasePath */ @@ -143,66 +159,40 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * * * The folders supported per platform are: * - * | | Windows | WinRT/UWP |macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | - * | ----------- | ------- | --------- |--------- | ---- | ---------- | ----- | ---------- | - * | HOME | X | X | X | | X | X | X | - * | DESKTOP | X | X | X | | X | X | | - * | DOCUMENTS | X | X | X | | X | | | - * | DOWNLOADS | Vista+ | X | X | | X | | | - * | MUSIC | X | X | X | | X | | | - * | PICTURES | X | X | X | | X | | | - * | PUBLICSHARE | | | X | | X | | | - * | SAVEDGAMES | Vista+ | | | | | | | - * | SCREENSHOTS | Vista+ | X | | | | | | - * | TEMPLATES | X | X | X | | X | | | - * | VIDEOS | X | X | X* | | X | | | + * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | + * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- | + * | HOME | X | X | | X | X | X | + * | DESKTOP | X | X | | X | X | | + * | DOCUMENTS | X | X | | X | | | + * | DOWNLOADS | Vista+ | X | | X | | | + * | MUSIC | X | X | | X | | | + * | PICTURES | X | X | | X | | | + * | PUBLICSHARE | | X | | X | | | + * | SAVEDGAMES | Vista+ | | | | | | + * | SCREENSHOTS | Vista+ | | | | | | + * | TEMPLATES | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | * * Note that on macOS/iOS, the Videos folder is called "Movies". * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetUserFolder */ typedef enum SDL_Folder { - /** The folder which contains all of the current user's data, preferences, - and documents. It usually contains most of the other folders. If a - requested folder does not exist, the home folder can be considered a safe - fallback to store a user's documents. */ - SDL_FOLDER_HOME, - /** The folder of files that are displayed on the desktop. Note that the - existence of a desktop folder does not guarantee that the system does - show icons on its desktop; certain GNU/Linux distros with a graphical - environment may not have desktop icons. */ - SDL_FOLDER_DESKTOP, - /** User document files, possibly application-specific. This is a good - place to save a user's projects. */ - SDL_FOLDER_DOCUMENTS, - /** Standard folder for user files downloaded from the internet. */ - SDL_FOLDER_DOWNLOADS, - /** Music files that can be played using a standard music player (mp3, - ogg...). */ - SDL_FOLDER_MUSIC, - /** Image files that can be displayed using a standard viewer (png, - jpg...). */ - SDL_FOLDER_PICTURES, - /** Files that are meant to be shared with other users on the same - computer. */ - SDL_FOLDER_PUBLICSHARE, - /** Save files for games. */ - SDL_FOLDER_SAVEDGAMES, - /** Application screenshots. */ - SDL_FOLDER_SCREENSHOTS, - /** Template files to be used when the user requests the desktop environment - to create a new file in a certain folder, such as "New Text File.txt". - Any file in the Templates folder can be used as a starting point for a - new file. */ - SDL_FOLDER_TEMPLATES, - /** Video files that can be played using a standard video player (mp4, - webm...). */ - SDL_FOLDER_VIDEOS, - /** total number of types in this enum, not a folder type by itself. */ - SDL_FOLDER_TOTAL + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ } SDL_Folder; /** @@ -226,13 +216,24 @@ typedef enum SDL_Folder * \returns either a null-terminated C string containing the full path to the * folder, or NULL if an error happened. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder); /* Abstract filesystem interface */ +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ typedef enum SDL_PathType { SDL_PATHTYPE_NONE, /**< path does not exist */ @@ -241,19 +242,27 @@ typedef enum SDL_PathType SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */ } SDL_PathType; +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ typedef struct SDL_PathInfo { - SDL_PathType type; /* the path type */ - Uint64 size; /* the file size in bytes */ - SDL_Time create_time; /* the time when the path was created */ - SDL_Time modify_time; /* the last time the path was modified */ - SDL_Time access_time; /* the last time the path was read */ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ } SDL_PathInfo; /** - * Flags for path matching + * Flags for path matching. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GlobDirectory * \sa SDL_GlobStorageDirectory @@ -263,73 +272,160 @@ typedef Uint32 SDL_GlobFlags; #define SDL_GLOB_CASEINSENSITIVE (1u << 0) /** - * Create a directory. + * Create a directory, and any missing parent directories. + * + * This reports success if `path` already exists as a directory. + * + * If parent directories are missing, it will also create them. Note that if + * this fails, it will not remove any parent directories it already made. * * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateDirectory(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); -/* Callback for directory enumeration. Return 1 to keep enumerating, - 0 to stop enumerating (no error), -1 to stop enumerating and - report an error. `dirname` is the directory being enumerated, - `fname` is the enumerated entry. */ -typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param dirname the directory that is being enumerated. + * \param fname the next entry in the enumeration. + * \returns how the enumeration should proceed. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); /** * Enumerate a directory through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. * * \param path the path of the directory to enumerate. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory. * - * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. * - * \since This function is available since SDL 3.0.0. + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemovePath(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); /** * Rename a file or directory. * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); /** * Copy a file. * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `newpath`'s previous contents will be gone, replaced with + * an incomplete copy of the data. To avoid this risk, it is recommended that + * the app copy to a temporary file in the same directory as `newpath`, and if + * the copy is successful, use SDL_RenamePath() to replace `newpath` with the + * temporary file. This will ensure that reads of `newpath` will either see a + * complete copy of the data, or it will see the pre-copy state of `newpath`. + * + * This function attempts to synchronize the newly-copied data to disk before + * returning, if the platform allows it, so that the renaming trick will not + * have a problem in a system crash or power failure, where the file could be + * renamed but the contents never made it from the system file cache to the + * physical disk. + * + * If the copy fails for any reason, the state of `newpath` is undefined. It + * might be half a copy, it might be the untouched data of what was already + * there, or it might be a zero-byte file, etc. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); /** * Get information about a filesystem path. @@ -337,21 +433,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const cha * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); /** * Enumerate a directory tree, filtered by pattern, and return a list. * * Files are filtered out if they don't match the string in `pattern`, which - * may contain wildcard characters '*' (match everything) and '?' (match one + * may contain wildcard characters '\*' (match everything) and '?' (match one * character). If pattern is NULL, no filtering is done and all results are * returned. Subdirectories are permitted, and are specified with a path - * separator of '/'. Wildcard characters '*' and '?' never match a path + * separator of '/'. Wildcard characters '\*' and '?' never match a path * separator. * * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching @@ -373,10 +469,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count); +/** + * Get what the system believes is the "current working directory." + * + * For systems without a concept of a current working directory, this will + * still attempt to provide something reasonable. + * + * SDL does not provide a means to _change_ the current working directory; for + * platforms without this concept, this would cause surprises with file access + * outside of SDL. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns a UTF-8 string of the current working directory in + * platform-dependent notation. NULL if there's a problem. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gamepad.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gamepad.h index 3d2d726..264f763 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gamepad.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gamepad.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,6 +51,24 @@ * If you would like to receive gamepad updates while the application is in * the background, you should set the following hint before calling * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. */ #ifndef SDL_gamepad_h_ @@ -58,9 +76,11 @@ #include #include -#include -#include +#include #include +#include +#include +#include #include #include @@ -72,7 +92,7 @@ extern "C" { /** * The structure used to identify an SDL gamepad * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Gamepad SDL_Gamepad; @@ -98,7 +118,7 @@ typedef enum SDL_GamepadType SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_GAMEPAD_TYPE_MAX + SDL_GAMEPAD_TYPE_COUNT } SDL_GamepadType; /** @@ -122,15 +142,15 @@ typedef enum SDL_GamepadType * You can query the labels for the face buttons using * SDL_GetGamepadButtonLabel() * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButton { SDL_GAMEPAD_BUTTON_INVALID = -1, - SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */ - SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */ - SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */ - SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */ + SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */ + SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */ + SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */ + SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */ SDL_GAMEPAD_BUTTON_BACK, SDL_GAMEPAD_BUTTON_GUIDE, SDL_GAMEPAD_BUTTON_START, @@ -142,18 +162,18 @@ typedef enum SDL_GamepadButton SDL_GAMEPAD_BUTTON_DPAD_DOWN, SDL_GAMEPAD_BUTTON_DPAD_LEFT, SDL_GAMEPAD_BUTTON_DPAD_RIGHT, - SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ - SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */ - SDL_GAMEPAD_BUTTON_MISC2, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC3, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC4, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC5, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC6, /* Additional button */ - SDL_GAMEPAD_BUTTON_MAX + SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */ + SDL_GAMEPAD_BUTTON_COUNT } SDL_GamepadButton; /** @@ -165,7 +185,7 @@ typedef enum SDL_GamepadButton * For a complete set, you should look at the button and gamepad type and have * a set of symbols that work well with your art style. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButtonLabel { @@ -192,7 +212,7 @@ typedef enum SDL_GamepadButtonLabel * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the * same range that will be reported by the lower-level SDL_GetJoystickAxis(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadAxis { @@ -203,7 +223,7 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_RIGHTY, SDL_GAMEPAD_AXIS_LEFT_TRIGGER, SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, - SDL_GAMEPAD_AXIS_MAX + SDL_GAMEPAD_AXIS_COUNT } SDL_GamepadAxis; /** @@ -214,7 +234,7 @@ typedef enum SDL_GamepadAxis * gamepad. This enum is used as part of SDL_GamepadBinding to specify those * mappings. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadBindingType { @@ -235,7 +255,7 @@ typedef enum SDL_GamepadBindingType * more with a simple text string. Those strings are parsed into a collection * of these structs to make it easier to operate on the data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetGamepadBindings */ @@ -293,6 +313,9 @@ typedef struct SDL_GamepadBinding * * Buttons can be used as a gamepad axes and vice versa. * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * * This string shows an example of a valid mapping for a gamepad: * * ```c @@ -305,10 +328,15 @@ typedef struct SDL_GamepadBinding * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); @@ -321,6 +349,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -330,21 +361,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * constrained environment. * * \param src the data stream for the mappings to be added. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the number of mappings added or -1 on failure; call SDL_GetError() * for more information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromFile * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ -extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); /** * Load a set of gamepad mappings from a file. @@ -355,6 +389,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -365,12 +402,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); @@ -379,12 +419,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file) * * This will generate gamepad events as needed if device mappings change. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. @@ -396,7 +436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); @@ -408,7 +448,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); * information. This should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUID @@ -425,7 +465,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid); * available; call SDL_GetError() for more information. This should * be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMappingForID @@ -442,26 +482,26 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); * \param instance_id the joystick instance ID. * \param mapping the mapping to use for this device, or NULL to clear the * mapping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMapping */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); /** * Return whether a gamepad is currently connected. * - * \returns SDL_TRUE if a gamepad is connected, SDL_FALSE otherwise. + * \returns true if a gamepad is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. @@ -472,7 +512,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasGamepad * \sa SDL_OpenGamepad @@ -483,15 +523,15 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); * Check if the given joystick is supported by the gamepad interface. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the given joystick is supported by the gamepad - * interface, SDL_FALSE if it isn't or it's an invalid index. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks * \sa SDL_OpenGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); /** * Get the implementation dependent name of a gamepad. @@ -502,7 +542,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); * \returns the name of the selected gamepad. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadName * \sa SDL_GetGamepads @@ -518,7 +558,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID * \returns the path of the selected gamepad. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPath * \sa SDL_GetGamepads @@ -533,7 +573,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepads @@ -549,7 +589,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID in * \returns the GUID of the selected gamepad. If called on an invalid index, * this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString * \sa SDL_GetGamepads @@ -566,7 +606,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID inst * \returns the USB vendor ID of the selected gamepad. If called on an invalid * index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendor * \sa SDL_GetGamepads @@ -583,7 +623,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID inst * \returns the USB product ID of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProduct * \sa SDL_GetGamepads @@ -600,7 +640,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID ins * \returns the product version of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersion * \sa SDL_GetGamepads @@ -615,7 +655,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_Joystic * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadType * \sa SDL_GetGamepads @@ -631,7 +671,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_Joystick * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepads @@ -648,7 +688,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys * \returns the mapping string. Returns NULL if no mapping is available. This * should be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads * \sa SDL_GetGamepadMapping @@ -662,7 +702,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID ins * \returns a gamepad identifier or NULL if an error occurred; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseGamepad * \sa SDL_IsGamepad @@ -677,7 +717,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instanc * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); @@ -687,7 +727,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID in * \param player_index the player index, which different from the instance ID. * \returns the SDL_Gamepad associated with a player index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_SetGamepadPlayerIndex @@ -717,7 +757,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int play * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); @@ -735,7 +775,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa * \returns the instance ID of the specified gamepad on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); @@ -747,7 +787,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad * \returns the implementation dependent name for the gamepad, or NULL if * there is no name or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadNameForID */ @@ -761,7 +801,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad * \returns the implementation dependent path for the gamepad, or NULL if * there is no path or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPathForID */ @@ -774,7 +814,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID */ @@ -787,7 +827,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRealGamepadTypeForID */ @@ -801,7 +841,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad * * \param gamepad the gamepad object to query. * \returns the player index for gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadPlayerIndex */ @@ -813,14 +853,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to adjust. * \param player_index player index to assign to this gamepad, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); /** * Get the USB vendor ID of an opened gamepad, if available. @@ -830,7 +870,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *game * \param gamepad the gamepad object to query. * \returns the USB vendor ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendorForID */ @@ -844,7 +884,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductForID */ @@ -858,7 +898,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersionForID */ @@ -872,7 +912,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gam * \param gamepad the gamepad object to query. * \returns the gamepad firmware version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); @@ -884,7 +924,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga * \param gamepad the gamepad object to query. * \returns the serial number, or NULL if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); @@ -897,7 +937,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamep * \param gamepad the gamepad object to query. * \returns the gamepad handle, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); @@ -909,7 +949,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepa * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); @@ -929,7 +969,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnection * battery. * \returns the current battery state. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); @@ -938,12 +978,12 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad * * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). - * \returns SDL_TRUE if the gamepad has been opened and is currently - * connected, or SDL_FALSE if not. + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** * Get the underlying joystick from a gamepad. @@ -961,7 +1001,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); @@ -973,12 +1013,12 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g * * \param enabled whether to process gamepad events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadEventsEnabled * \sa SDL_UpdateGamepads */ -extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); /** * Query the state of gamepad event processing. @@ -986,14 +1026,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * and check the state of the gamepad when you want gamepad information. * - * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE - * otherwise. + * \returns true if gamepad events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); /** * Get the SDL joystick layer bindings for a gamepad. @@ -1005,7 +1044,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); @@ -1016,7 +1055,7 @@ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gam * enabled. Under such circumstances, it will not be necessary to call this * function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); @@ -1032,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); * \returns the SDL_GamepadType enum corresponding to the input string, or * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForType */ @@ -1046,7 +1085,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeFromString */ @@ -1068,7 +1107,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_Gamepad * \returns the SDL_GamepadAxis enum corresponding to the input string, or * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForAxis */ @@ -1082,7 +1121,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAxisFromString */ @@ -1096,14 +1135,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad * * \param gamepad a gamepad. * \param axis an axis enum value (an SDL_GamepadAxis value). - * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. + * \returns true if the gamepad has this axis, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); /** * Get the current state of an axis control on a gamepad. @@ -1122,7 +1161,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD * \returns axis state (including 0) on success or 0 (also) on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis * \sa SDL_GetGamepadButton @@ -1141,7 +1180,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_ * \returns the SDL_GamepadButton enum corresponding to the input string, or * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForButton */ @@ -1155,7 +1194,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonFromString */ @@ -1169,28 +1208,27 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep * * \param gamepad a gamepad. * \param button a button enum value (an SDL_GamepadButton value). - * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. + * \returns true if the gamepad has this button, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the current state of a button on a gamepad. * * \param gamepad a gamepad. * \param button a button index (one of the SDL_GamepadButton values). - * \returns 1 for pressed state or 0 for not pressed state or failure; call - * SDL_GetError() for more information. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the label of a button on a gamepad. @@ -1199,7 +1237,7 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabel */ @@ -1212,7 +1250,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabelForType */ @@ -1224,7 +1262,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL * \param gamepad a gamepad. * \returns number of touchpads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ @@ -1238,7 +1276,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad) * \param touchpad a touchpad. * \returns number of supported simultaneous fingers. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTouchpadFinger * \sa SDL_GetNumGamepadTouchpads @@ -1251,35 +1289,36 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga * \param gamepad a gamepad. * \param touchpad a touchpad. * \param finger a finger. - * \param state filled with state. - * \param x filled with x position, normalized 0 to 1, with the origin in the - * upper left. - * \param y filled with y position, normalized 0 to 1, with the origin in the - * upper left. - * \param pressure filled with pressure value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); /** * Return whether a gamepad has a particular sensor. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. + * \returns true if the sensor exists, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadSensorData * \sa SDL_GetGamepadSensorDataRate * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Set whether data reporting for a gamepad sensor is enabled. @@ -1287,28 +1326,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, * \param gamepad the gamepad to update. * \param type the type of sensor to enable/disable. * \param enabled whether data reporting should be enabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasSensor * \sa SDL_GamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); /** * Query whether sensor data reporting is enabled for a gamepad. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. + * \returns true if the sensor is enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Get the data rate (number of events per second) of a gamepad sensor. @@ -1317,7 +1356,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep * \param type the type of sensor to query. * \returns the data rate, or 0.0f if the data rate is not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); @@ -1331,12 +1370,12 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game * \param type the type of sensor to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); /** * Start a rumble effect on a gamepad. @@ -1353,12 +1392,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamep * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the gamepad's triggers. @@ -1379,14 +1418,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uin * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a gamepad's LED color. @@ -1401,12 +1440,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *game * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** * Send a gamepad specific effect packet. @@ -1414,12 +1453,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uin * \param gamepad the gamepad to affect. * \param data the data to send to the gamepad. * \param size the size of the data to send to the gamepad. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); /** * Close a gamepad previously opened with SDL_OpenGamepad(). @@ -1427,7 +1466,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenGamepad */ @@ -1441,7 +1480,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); * \param button a button on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis */ @@ -1454,7 +1493,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt * \param axis an axis on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForButton */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gpu.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gpu.h index bba47cc..fa870a5 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gpu.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_gpu.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,281 @@ /** * # CategoryGPU * - * Include file for SDL GPU API functions + * The GPU API offers a cross-platform way for apps to talk to modern graphics + * hardware. It offers both 3D graphics and compute support, in the style of + * Metal, Vulkan, and Direct3D 12. + * + * A basic workflow might be something like this: + * + * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to + * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you + * can render offscreen entirely, perhaps for image processing, and not use a + * window at all. + * + * Next the app prepares static data (things that are created once and used + * over and over). For example: + * + * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader(). + * - Vertex buffers (arrays of geometry data) and other data rendering will + * need: use SDL_UploadToGPUBuffer(). + * - Textures (images): use SDL_UploadToGPUTexture(). + * - Samplers (how textures should be read from): use SDL_CreateGPUSampler(). + * - Render pipelines (precalculated rendering state): use + * SDL_CreateGPUGraphicsPipeline() + * + * To render, the app creates one or more command buffers, with + * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering + * instructions that will be submitted to the GPU in batch. Complex scenes can + * use multiple command buffers, maybe configured across multiple threads in + * parallel, as long as they are submitted in the correct order, but many apps + * will just need one command buffer per frame. + * + * Rendering can happen to a texture (what other APIs call a "render target") + * or it can happen to the swapchain texture (which is just a special texture + * that represents a window's contents). The app can use + * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. */ #ifndef SDL_gpu_h_ @@ -44,132 +318,394 @@ extern "C" { /* Type Declarations */ +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ typedef struct SDL_GPUFence SDL_GPUFence; +/** + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUPrimitiveType { - SDL_GPU_PRIMITIVETYPE_POINTLIST, - SDL_GPU_PRIMITIVETYPE_LINELIST, - SDL_GPU_PRIMITIVETYPE_LINESTRIP, - SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, - SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ } SDL_GPUPrimitiveType; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPULoadOp { - SDL_GPU_LOADOP_LOAD, - SDL_GPU_LOADOP_CLEAR, - SDL_GPU_LOADOP_DONT_CARE + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ } SDL_GPULoadOp; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPUStoreOp { - SDL_GPU_STOREOP_STORE, - SDL_GPU_STOREOP_DONT_CARE + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ } SDL_GPUStoreOp; +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUIndexElementSize { - SDL_GPU_INDEXELEMENTSIZE_16BIT, - SDL_GPU_INDEXELEMENTSIZE_32BIT + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ } SDL_GPUIndexElementSize; -/* Texture format support varies depending on driver, hardware, and usage flags. - * In general, you should use SDL_GPUTextureSupportsFormat to query if a format - * is supported before using it. However, there are a few guaranteed formats. +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE * * For SAMPLER usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R8G8_SNORM - * - R8G8B8A8_SNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB - * - D16_UNORM + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM * * For COLOR_TARGET usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB * * For STORAGE usages, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - R8G8B8A8_SNORM - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT * - * For DEPTH_STENCIL_TARGET usage, the following formats are universally supported: - * - D16_UNORM - * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT - * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT * - * Unless D16_UNORM is sufficient for your purposes, always check which - * of D24/D32 is supported before creating a depth-stencil texture! + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat */ typedef enum SDL_GPUTextureFormat { - SDL_GPU_TEXTUREFORMAT_INVALID = -1, + SDL_GPU_TEXTUREFORMAT_INVALID, /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, - SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, - SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, - SDL_GPU_TEXTUREFORMAT_R8_UNORM, - SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, /* Compressed Unsigned Normalized Float Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC1_UNORM, - SDL_GPU_TEXTUREFORMAT_BC2_UNORM, - SDL_GPU_TEXTUREFORMAT_BC3_UNORM, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, /* Signed Float Color Formats */ SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, @@ -177,6 +713,8 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, /* Unsigned Integer Color Formats */ SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_UINT, @@ -184,48 +722,153 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, /* SRGB Unsigned Normalized Color Formats */ SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, /* Compressed SRGB Unsigned Normalized Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC3_UNORM_SRGB, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, /* Depth Formats */ SDL_GPU_TEXTUREFORMAT_D16_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D32_FLOAT, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, - SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT } SDL_GPUTextureFormat; -typedef enum SDL_GPUTextureUsageFlagBits -{ - SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT = 0x00000001, - SDL_GPU_TEXTUREUSAGE_COLOR_TARGET_BIT = 0x00000002, - SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET_BIT = 0x00000004, - SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUTextureUsageFlagBits; - +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef Uint32 SDL_GPUTextureUsageFlags; +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef enum SDL_GPUTextureType { - SDL_GPU_TEXTURETYPE_2D, - SDL_GPU_TEXTURETYPE_2D_ARRAY, - SDL_GPU_TEXTURETYPE_3D, - SDL_GPU_TEXTURETYPE_CUBE + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ } SDL_GPUTextureType; +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ typedef enum SDL_GPUSampleCount { - SDL_GPU_SAMPLECOUNT_1, - SDL_GPU_SAMPLECOUNT_2, - SDL_GPU_SAMPLECOUNT_4, - SDL_GPU_SAMPLECOUNT_8 + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ } SDL_GPUSampleCount; + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_GPUCubeMapFace { SDL_GPU_CUBEMAPFACE_POSITIVEX, @@ -236,45 +879,87 @@ typedef enum SDL_GPUCubeMapFace SDL_GPU_CUBEMAPFACE_NEGATIVEZ } SDL_GPUCubeMapFace; -typedef enum SDL_GPUBufferUsageFlagBits -{ - SDL_GPU_BUFFERUSAGE_VERTEX_BIT = 0x00000001, - SDL_GPU_BUFFERUSAGE_INDEX_BIT = 0x00000002, - SDL_GPU_BUFFERUSAGE_INDIRECT_BIT = 0x00000004, - SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUBufferUsageFlagBits; - +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ typedef Uint32 SDL_GPUBufferUsageFlags; +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef enum SDL_GPUTransferBufferUsage { SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD } SDL_GPUTransferBufferUsage; +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef enum SDL_GPUShaderStage { SDL_GPU_SHADERSTAGE_VERTEX, SDL_GPU_SHADERSTAGE_FRAGMENT } SDL_GPUShaderStage; -typedef enum SDL_GPUShaderFormatFlagBits -{ - SDL_GPU_SHADERFORMAT_INVALID = 0x00000000, - SDL_GPU_SHADERFORMAT_SECRET = 0x00000001, /* NDA'd platforms */ - SDL_GPU_SHADERFORMAT_SPIRV = 0x00000002, /* Vulkan */ - SDL_GPU_SHADERFORMAT_DXBC = 0x00000004, /* D3D11 (Shader Model 5_0) */ - SDL_GPU_SHADERFORMAT_DXIL = 0x00000008, /* D3D12 */ - SDL_GPU_SHADERFORMAT_MSL = 0x00000010, /* Metal */ - SDL_GPU_SHADERFORMAT_METALLIB = 0x00000020, /* Metal */ -} SDL_GPUShaderFormatFlagBits; - +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef Uint32 SDL_GPUShaderFormat; +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexElementFormat { + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + /* 32-bit Signed Integers */ SDL_GPU_VERTEXELEMENTFORMAT_INT, SDL_GPU_VERTEXELEMENTFORMAT_INT2, @@ -330,125 +1015,230 @@ typedef enum SDL_GPUVertexElementFormat SDL_GPU_VERTEXELEMENTFORMAT_HALF4 } SDL_GPUVertexElementFormat; +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexInputRate { - SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, - SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ } SDL_GPUVertexInputRate; +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFillMode { - SDL_GPU_FILLMODE_FILL, - SDL_GPU_FILLMODE_LINE + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ } SDL_GPUFillMode; +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCullMode { - SDL_GPU_CULLMODE_NONE, - SDL_GPU_CULLMODE_FRONT, - SDL_GPU_CULLMODE_BACK + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ } SDL_GPUCullMode; +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFrontFace { - SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, - SDL_GPU_FRONTFACE_CLOCKWISE + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ } SDL_GPUFrontFace; +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCompareOp { - SDL_GPU_COMPAREOP_NEVER, - SDL_GPU_COMPAREOP_LESS, - SDL_GPU_COMPAREOP_EQUAL, - SDL_GPU_COMPAREOP_LESS_OR_EQUAL, - SDL_GPU_COMPAREOP_GREATER, - SDL_GPU_COMPAREOP_NOT_EQUAL, - SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, - SDL_GPU_COMPAREOP_ALWAYS + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ } SDL_GPUCompareOp; +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUStencilOp { - SDL_GPU_STENCILOP_KEEP, - SDL_GPU_STENCILOP_ZERO, - SDL_GPU_STENCILOP_REPLACE, - SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_INVERT, - SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, - SDL_GPU_STENCILOP_DECREMENT_AND_WRAP + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ } SDL_GPUStencilOp; +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendOp { - SDL_GPU_BLENDOP_ADD, - SDL_GPU_BLENDOP_SUBTRACT, - SDL_GPU_BLENDOP_REVERSE_SUBTRACT, - SDL_GPU_BLENDOP_MIN, - SDL_GPU_BLENDOP_MAX + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ } SDL_GPUBlendOp; +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendFactor { - SDL_GPU_BLENDFACTOR_ZERO, - SDL_GPU_BLENDFACTOR_ONE, - SDL_GPU_BLENDFACTOR_SRC_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, - SDL_GPU_BLENDFACTOR_DST_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_DST_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, - SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ } SDL_GPUBlendFactor; -typedef enum SDL_GPUColorComponentFlagBits -{ - SDL_GPU_COLORCOMPONENT_R_BIT = 0x00000001, - SDL_GPU_COLORCOMPONENT_G_BIT = 0x00000002, - SDL_GPU_COLORCOMPONENT_B_BIT = 0x00000004, - SDL_GPU_COLORCOMPONENT_A_BIT = 0x00000008 -} SDL_GPUColorComponentFlagBits; - +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef Uint8 SDL_GPUColorComponentFlags; +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUFilter { - SDL_GPU_FILTER_NEAREST, - SDL_GPU_FILTER_LINEAR + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ } SDL_GPUFilter; +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerMipmapMode { - SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, - SDL_GPU_SAMPLERMIPMAPMODE_LINEAR + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ } SDL_GPUSamplerMipmapMode; +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerAddressMode { - SDL_GPU_SAMPLERADDRESSMODE_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ } SDL_GPUSamplerAddressMode; -/* - * VSYNC: - * Waits for vblank before presenting. - * If there is a pending image to present, the new image is enqueued for presentation. - * Disallows tearing at the cost of visual latency. - * When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight. - * IMMEDIATE: - * Immediately presents. - * Lowest latency option, but tearing may occur. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. - * MAILBOX: - * Waits for vblank before presenting. No tearing is possible. - * If there is a pending image to present, the pending image is replaced by the new image. - * Similar to VSYNC, but with reduced visual latency. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUPresentMode { @@ -457,493 +1247,866 @@ typedef enum SDL_GPUPresentMode SDL_GPU_PRESENTMODE_MAILBOX } SDL_GPUPresentMode; -/* - * SDR: - * B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. Blends raw pixel values. - * SDR_LINEAR: - * B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. Blends in linear space. - * HDR_EXTENDED_LINEAR: - * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. Blends in linear space. - * HDR10_ST2048: - * A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding. Blends raw pixel values. (TODO: verify this) +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUSwapchainComposition { SDL_GPU_SWAPCHAINCOMPOSITION_SDR, SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, - SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 } SDL_GPUSwapchainComposition; -typedef enum SDL_GPUDriver -{ - SDL_GPU_DRIVER_INVALID = -1, - SDL_GPU_DRIVER_SECRET, /* NDA'd platforms */ - SDL_GPU_DRIVER_VULKAN, - SDL_GPU_DRIVER_D3D11, - SDL_GPU_DRIVER_D3D12, - SDL_GPU_DRIVER_METAL -} SDL_GPUDriver; - /* Structures */ -typedef struct SDL_GPUDepthStencilValue -{ - float depth; - Uint8 stencil; -} SDL_GPUDepthStencilValue; - +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ typedef struct SDL_GPUViewport { - float x; - float y; - float w; - float h; - float minDepth; - float maxDepth; + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ } SDL_GPUViewport; +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureTransferInfo { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; /* starting location of the image data */ - Uint32 imagePitch; /* number of pixels from one row to the next */ - Uint32 imageHeight; /* number of rows from one layer/depth-slice to the next */ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ } SDL_GPUTextureTransferInfo; +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUTransferBufferLocation { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ } SDL_GPUTransferBufferLocation; +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + */ typedef struct SDL_GPUTextureLocation { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ } SDL_GPUTextureLocation; +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; - Uint32 w; - Uint32 h; - Uint32 d; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ } SDL_GPUTextureRegion; +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ typedef struct SDL_GPUBlitRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; - Uint32 x; - Uint32 y; - Uint32 w; - Uint32 h; + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ } SDL_GPUBlitRegion; +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + */ typedef struct SDL_GPUBufferLocation { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ } SDL_GPUBufferLocation; +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUBufferRegion { - SDL_GPUBuffer *buffer; - Uint32 offset; - Uint32 size; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ } SDL_GPUBufferRegion; -/* Note that the `firstVertex` and `firstInstance` parameters are NOT compatible with - * built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If - * your shader depends on these variables, the correlating draw call parameter MUST - * be 0. +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect */ typedef struct SDL_GPUIndirectDrawCommand { - Uint32 vertexCount; /* number of vertices to draw */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstVertex; /* index of the first vertex to draw */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ typedef struct SDL_GPUIndexedIndirectDrawCommand { - Uint32 indexCount; /* number of vertices to draw per instance */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstIndex; /* base index within the index buffer */ - Sint32 vertexOffset; /* value added to vertex index before indexing into the vertex buffer */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndexedIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ typedef struct SDL_GPUIndirectDispatchCommand { - Uint32 groupCountX; - Uint32 groupCountY; - Uint32 groupCountZ; + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ } SDL_GPUIndirectDispatchCommand; /* State structures */ +/** + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef struct SDL_GPUSamplerCreateInfo { - SDL_GPUFilter minFilter; - SDL_GPUFilter magFilter; - SDL_GPUSamplerMipmapMode mipmapMode; - SDL_GPUSamplerAddressMode addressModeU; - SDL_GPUSamplerAddressMode addressModeV; - SDL_GPUSamplerAddressMode addressModeW; - float mipLodBias; - SDL_bool anisotropyEnable; - float maxAnisotropy; - SDL_bool compareEnable; - SDL_GPUCompareOp compareOp; - float minLod; - float maxLod; + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUSamplerCreateInfo; -typedef struct SDL_GPUVertexBinding +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexBufferDescription { - Uint32 binding; - Uint32 stride; - SDL_GPUVertexInputRate inputRate; - Uint32 instanceStepRate; /* ignored unless inputRate is INSTANCE */ -} SDL_GPUVertexBinding; + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */ +} SDL_GPUVertexBufferDescription; +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + */ typedef struct SDL_GPUVertexAttribute { - Uint32 location; - Uint32 binding; - SDL_GPUVertexElementFormat format; - Uint32 offset; + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ } SDL_GPUVertexAttribute; +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + */ typedef struct SDL_GPUVertexInputState { - const SDL_GPUVertexBinding *vertexBindings; - Uint32 vertexBindingCount; - const SDL_GPUVertexAttribute *vertexAttributes; - Uint32 vertexAttributeCount; + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ } SDL_GPUVertexInputState; +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ typedef struct SDL_GPUStencilOpState { - SDL_GPUStencilOp failOp; - SDL_GPUStencilOp passOp; - SDL_GPUStencilOp depthFailOp; - SDL_GPUCompareOp compareOp; + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ } SDL_GPUStencilOpState; -typedef struct SDL_GPUColorAttachmentBlendState +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState { - SDL_bool blendEnable; - SDL_GPUBlendFactor srcColorBlendFactor; - SDL_GPUBlendFactor dstColorBlendFactor; - SDL_GPUBlendOp colorBlendOp; - SDL_GPUBlendFactor srcAlphaBlendFactor; - SDL_GPUBlendFactor dstAlphaBlendFactor; - SDL_GPUBlendOp alphaBlendOp; - SDL_GPUColorComponentFlags colorWriteMask; -} SDL_GPUColorAttachmentBlendState; + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef struct SDL_GPUShaderCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - SDL_GPUShaderStage stage; - Uint32 samplerCount; - Uint32 storageTextureCount; - Uint32 storageBufferCount; - Uint32 uniformBufferCount; + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUShaderCreateInfo; +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + */ typedef struct SDL_GPUTextureCreateInfo { - SDL_GPUTextureType type; - SDL_GPUTextureFormat format; - SDL_GPUTextureUsageFlags usageFlags; - Uint32 width; - Uint32 height; - Uint32 layerCountOrDepth; - Uint32 levelCount; - SDL_GPUSampleCount sampleCount; + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTextureCreateInfo; -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" - +/** + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + */ typedef struct SDL_GPUBufferCreateInfo { - SDL_GPUBufferUsageFlags usageFlags; - Uint32 sizeInBytes; + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUBufferCreateInfo; +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef struct SDL_GPUTransferBufferCreateInfo { - SDL_GPUTransferBufferUsage usage; - Uint32 sizeInBytes; + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTransferBufferCreateInfo; /* Pipeline state structures */ +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if + * enable_depth_clip is true. If you rely on this clamp+clip behavior, + * consider enabling depth clip and then manually clamping depth in your + * fragment shaders on Metal and Vulkan. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPURasterizerState { - SDL_GPUFillMode fillMode; - SDL_GPUCullMode cullMode; - SDL_GPUFrontFace frontFace; - SDL_bool depthBiasEnable; - float depthBiasConstantFactor; - float depthBiasClamp; - float depthBiasSlopeFactor; + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; } SDL_GPURasterizerState; +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUMultisampleState { - SDL_GPUSampleCount sampleCount; - Uint32 sampleMask; + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */ + bool enable_mask; /**< Enables sample masking. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUMultisampleState; +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUDepthStencilState { - SDL_bool depthTestEnable; - SDL_bool depthWriteEnable; - SDL_GPUCompareOp compareOp; - SDL_bool stencilTestEnable; - SDL_GPUStencilOpState backStencilState; - SDL_GPUStencilOpState frontStencilState; - Uint8 compareMask; - Uint8 writeMask; - Uint8 reference; + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUDepthStencilState; -typedef struct SDL_GPUColorAttachmentDescription +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription { - SDL_GPUTextureFormat format; - SDL_GPUColorAttachmentBlendState blendState; -} SDL_GPUColorAttachmentDescription; + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; -typedef struct SDL_GPUGraphicsPipelineAttachmentInfo +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo { - SDL_GPUColorAttachmentDescription *colorAttachmentDescriptions; - Uint32 colorAttachmentCount; - SDL_bool hasDepthStencilAttachment; - SDL_GPUTextureFormat depthStencilFormat; -} SDL_GPUGraphicsPipelineAttachmentInfo; + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ typedef struct SDL_GPUGraphicsPipelineCreateInfo { - SDL_GPUShader *vertexShader; - SDL_GPUShader *fragmentShader; - SDL_GPUVertexInputState vertexInputState; - SDL_GPUPrimitiveType primitiveType; - SDL_GPURasterizerState rasterizerState; - SDL_GPUMultisampleState multisampleState; - SDL_GPUDepthStencilState depthStencilState; - SDL_GPUGraphicsPipelineAttachmentInfo attachmentInfo; - float blendConstants[4]; + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUGraphicsPipelineCreateInfo; +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + */ typedef struct SDL_GPUComputePipelineCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - Uint32 readOnlyStorageTextureCount; - Uint32 readOnlyStorageBufferCount; - Uint32 writeOnlyStorageTextureCount; - Uint32 writeOnlyStorageBufferCount; - Uint32 uniformBufferCount; - Uint32 threadCountX; - Uint32 threadCountY; - Uint32 threadCountZ; + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUComputePipelineCreateInfo; -typedef struct SDL_GPUColorAttachmentInfo +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo { - /* The texture that will be used as a color attachment by a render pass. */ - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; /* For 3D textures, you can bind an individual depth plane as an attachment. */ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; - /* Can be ignored by RenderPass if CLEAR is not used */ - SDL_FColor clearColor; - - /* Determines what is done with the texture at the beginning of the render pass. - * - * LOAD: - * Loads the data currently in the texture. - * - * CLEAR: - * Clears the texture to a single color. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the texture at the end of the render pass. - * - * STORE: - * Stores the results of the render pass in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and loadOp is not LOAD */ - SDL_bool cycle; -} SDL_GPUColorAttachmentInfo; - -typedef struct SDL_GPUDepthStencilAttachmentInfo +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo { - /* The texture that will be used as the depth stencil attachment by a render pass. */ - SDL_GPUTexture *texture; + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; - /* Can be ignored by the render pass if CLEAR is not used */ - SDL_GPUDepthStencilValue depthStencilClearValue; - - /* Determines what is done with the depth values at the beginning of the render pass. - * - * LOAD: - * Loads the depth values currently in the texture. - * - * CLEAR: - * Clears the texture to a single depth. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the depth values at the end of the render pass. - * - * STORE: - * Stores the depth results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* Determines what is done with the stencil values at the beginning of the render pass. - * - * LOAD: - * Loads the stencil values currently in the texture. - * - * CLEAR: - * Clears the texture to a single stencil value. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp stencilLoadOp; - - /* Determines what is done with the stencil values at the end of the render pass. - * - * STORE: - * Stores the stencil results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp stencilStoreOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and any load ops are not LOAD */ - SDL_bool cycle; -} SDL_GPUDepthStencilAttachmentInfo; +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; /* Binding structs */ +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + */ typedef struct SDL_GPUBufferBinding { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ } SDL_GPUBufferBinding; +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ typedef struct SDL_GPUTextureSamplerBinding { - SDL_GPUTexture *texture; - SDL_GPUSampler *sampler; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ } SDL_GPUTextureSamplerBinding; -typedef struct SDL_GPUStorageBufferWriteOnlyBinding +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding { - SDL_GPUBuffer *buffer; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; - /* if SDL_TRUE, cycles the buffer if it is bound. */ - SDL_bool cycle; -} SDL_GPUStorageBufferWriteOnlyBinding; - -typedef struct SDL_GPUStorageTextureWriteOnlyBinding +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - - /* if SDL_TRUE, cycles the texture if the texture is bound. */ - SDL_bool cycle; -} SDL_GPUStorageTextureWriteOnlyBinding; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; /* Functions */ /* Device */ /** - * Creates a GPU context. + * Checks for GPU runtime support. * - * \param formatFlags a bitflag indicating which shader formats the app is - * able to provide. - * \param debugMode enable debug mode properties and validations. + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. * \param name the preferred GPU driver, or NULL to let SDL pick the optimal * driver. - * \returns a GPU context on success or NULL on failure. + * \returns true if supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( - SDL_GPUShaderFormat formatFlags, - SDL_bool debugMode, + SDL_GPUShaderFormat format_flags, + bool debug_mode, const char *name); /** @@ -951,26 +2114,26 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * * These are the supported properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL`: enable debug mode properties - * and validations, defaults to SDL_TRUE. - * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL`: enable to prefer energy - * efficiency over maximum GPU performance, defaults to SDL_FALSE. + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to * use, if a specific one is desired. * * These are the current shader format properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to * provide shaders for an NDA platform. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to * provide SPIR-V shaders if applicable. - * - SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL`: The app is able to provide - * DXBC shaders if applicable - * `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to * provide DXIL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL`: The app is able to provide - * MSL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to * provide Metal shader libraries if applicable. * * With the D3D12 renderer: @@ -979,25 +2142,28 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * use for all vertex semantics, default is "TEXCOORD". * * \param props the properties to use. - * \returns a GPU context on success or NULL on failure. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( SDL_PropertiesID props); -#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" -#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL "SDL.gpu.device.create.shaders.secret" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" /** @@ -1005,70 +2171,132 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( * * \param device a GPU Context to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUDevice */ extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); /** - * Returns the backend used to create this GPU context. + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. * * \param device a GPU context to query. - * \returns an SDL_GPUDriver value, or SDL_GPU_DRIVER_INVALID on error. + * \returns the name of the device's driver, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); /* State Creation */ /** * Creates a pipeline object to be used in a compute workflow. * - * Shader resource bindings must be authored to follow a particular order. For - * SPIR-V shaders, use the following resource sets: 0: Read-only storage - * textures, followed by read-only storage buffers 1: Write-only storage - * textures, followed by write-only storage buffers 2: Uniform buffers + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Read-only storage textures, followed by read-only storage - * buffers For u registers: Write-only storage textures, followed by - * write-only storage buffers For b registers: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXIL shaders, use the following register order: (t[n], space0): - * Read-only storage textures, followed by read-only storage buffers (u[n], - * space1): Write-only storage textures, followed by write-only storage - * buffers (b[n], space2): Uniform buffers + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers * - * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, - * followed by write-only storage buffers, followed by write-only storage - * buffers For [[texture]]: Read-only storage textures, followed by write-only - * storage textures + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. * * \param device a GPU Context. - * \param computePipelineCreateInfo a struct describing the state of the - * requested compute pipeline. - * \returns a compute pipeline object on success, or NULL on failure. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUComputePipeline * \sa SDL_ReleaseGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipelineCreateInfo *computePipelineCreateInfo); + const SDL_GPUComputePipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" /** * Creates a pipeline object to be used in a graphics workflow. * - * \param device a GPU Context. - * \param pipelineCreateInfo a struct describing the state of the desired - * graphics pipeline. - * \returns a graphics pipeline object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUShader * \sa SDL_BindGPUGraphicsPipeline @@ -1076,26 +2304,36 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipelineCreateInfo *pipelineCreateInfo); + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" /** * Creates a sampler object to be used when binding textures in a graphics * workflow. * - * \param device a GPU Context. - * \param samplerCreateInfo a struct describing the state of the desired - * sampler. - * \returns a sampler object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUVertexSamplers * \sa SDL_BindGPUFragmentSamplers - * \sa SDL_ReleaseSampler + * \sa SDL_ReleaseGPUSampler */ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( SDL_GPUDevice *device, - SDL_GPUSamplerCreateInfo *samplerCreateInfo); + const SDL_GPUSamplerCreateInfo *createinfo); + +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" /** * Creates a shader to be used when creating a graphics pipeline. @@ -1103,46 +2341,78 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * Shader resource bindings must be authored to follow a particular order * depending on the shader format. * - * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: - * Sampled textures, followed by storage textures, followed by storage buffers - * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by - * storage textures, followed by storage buffers 3: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Sampled textures, followed by storage textures, followed by - * storage buffers For s registers: Samplers with indices corresponding to the - * sampled textures For b registers: Uniform buffers + * For vertex shaders: * - * For DXIL shaders, use the following register order: For vertex shaders: - * (t[n], space0): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space0): Samplers with indices corresponding to the - * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n], - * space2): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space2): Samplers with indices corresponding to the - * sampled textures (b[n], space3): Uniform buffers + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers * - * For MSL/metallib, use the following order: For [[texture]]: Sampled - * textures, followed by storage textures For [[sampler]]: Samplers with - * indices corresponding to the sampled textures For [[buffer]]: Uniform - * buffers, followed by storage buffers. Vertex buffer 0 is bound at - * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than - * manually authoring vertex buffer indices, use the [[stage_in]] attribute - * which will automatically use the vertex input information from the - * SDL_GPUPipeline. + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. * * \param device a GPU Context. - * \param shaderCreateInfo a struct describing the state of the desired - * shader. - * \returns a shader object on success, or NULL on failure. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUGraphicsPipeline * \sa SDL_ReleaseGPUShader */ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( SDL_GPUDevice *device, - SDL_GPUShaderCreateInfo *shaderCreateInfo); + const SDL_GPUShaderCreateInfo *createinfo); + +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" /** * Creates a texture object to be used in graphics or compute workflows. @@ -1157,12 +2427,36 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * - * \param device a GPU Context. - * \param textureCreateInfo a struct describing the state of the texture to - * create. - * \returns a texture object on success, or NULL on failure. + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the texture to create. + * \returns a texture object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture * \sa SDL_DownloadFromGPUTexture @@ -1177,7 +2471,15 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( */ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, - SDL_GPUTextureCreateInfo *textureCreateInfo); + const SDL_GPUTextureCreateInfo *createinfo); + +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" /** * Creates a buffer object to be used in graphics or compute workflows. @@ -1188,35 +2490,63 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * Note that certain combinations of usage flags are invalid. For example, a * buffer cannot have both the VERTEX and INDEX flags. * - * \param device a GPU Context. - * \param bufferCreateInfo a struct describing the state of the buffer to - * create. - * \returns a buffer object on success, or NULL on failure. + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer * \sa SDL_BindGPUVertexBuffers * \sa SDL_BindGPUIndexBuffer * \sa SDL_BindGPUVertexStorageBuffers * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect * \sa SDL_ReleaseGPUBuffer */ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( SDL_GPUDevice *device, - SDL_GPUBufferCreateInfo *bufferCreateInfo); + const SDL_GPUBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" /** * Creates a transfer buffer to be used when uploading to or downloading from * graphics resources. * - * \param device a GPU Context. - * \param transferBufferCreateInfo a struct describing the state of the - * transfer buffer to create. - * \returns a transfer buffer on success, or NULL on failure. + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer @@ -1226,20 +2556,28 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( */ extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBufferCreateInfo *transferBufferCreateInfo); + const SDL_GPUTransferBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" /* Debug Naming */ /** * Sets an arbitrary string constant to label a buffer. * - * Useful for debugging. + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. * * \param device a GPU Context. * \param buffer a buffer to attach the name to. * \param text a UTF-8 string constant to mark as the name of the buffer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( SDL_GPUDevice *device, @@ -1249,13 +2587,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( /** * Sets an arbitrary string constant to label a texture. * - * Useful for debugging. + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. * * \param device a GPU Context. * \param texture a texture to attach the name to. * \param text a UTF-8 string constant to mark as the name of the texture. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( SDL_GPUDevice *device, @@ -1267,13 +2612,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( * * Useful for debugging. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param text a UTF-8 string constant to insert as the label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *text); /** @@ -1290,28 +2635,28 @@ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( * pass rather than the command buffer. For best results, if you push a debug * group during a pass, always pop it in the same pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param name a UTF-8 string constant that names the group. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PopGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *name); /** * Ends the most-recently pushed debug group. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /* Disposal */ @@ -1323,7 +2668,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( * \param device a GPU context. * \param texture a texture to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( SDL_GPUDevice *device, @@ -1332,12 +2677,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( /** * Frees the given sampler as soon as it is safe to do so. * - * You must not reference the texture after calling this function. + * You must not reference the sampler after calling this function. * * \param device a GPU context. * \param sampler a sampler to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( SDL_GPUDevice *device, @@ -1351,7 +2696,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( * \param device a GPU context. * \param buffer a buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( SDL_GPUDevice *device, @@ -1363,13 +2708,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( * You must not reference the transfer buffer after calling this function. * * \param device a GPU context. - * \param transferBuffer a transfer buffer to be destroyed. + * \param transfer_buffer a transfer buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /** * Frees the given compute pipeline as soon as it is safe to do so. @@ -1377,13 +2722,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( * You must not reference the compute pipeline after calling this function. * * \param device a GPU context. - * \param computePipeline a compute pipeline to be destroyed. + * \param compute_pipeline a compute pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePipeline *compute_pipeline); /** * Frees the given shader as soon as it is safe to do so. @@ -1393,7 +2738,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( * \param device a GPU context. * \param shader a shader to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( SDL_GPUDevice *device, @@ -1405,29 +2750,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( * You must not reference the graphics pipeline after calling this function. * * \param device a GPU context. - * \param graphicsPipeline a graphics pipeline to be destroyed. + * \param graphics_pipeline a graphics pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipeline *graphicsPipeline); - -/* - * COMMAND BUFFERS - * - * Render state is managed via command buffers. - * When setting render state, that state is always local to the command buffer. - * - * Commands only begin execution on the GPU once Submit is called. - * Once the command buffer is submitted, it is no longer valid to use it. - * - * Command buffers are executed in submission order. If you submit command buffer A and then command buffer B - * all commands in A will begin executing before any command in B begins executing. - * - * In multi-threading scenarios, you should acquire and submit a command buffer on the same thread. - * As long as you satisfy this requirement, all functionality related to command buffers is thread-safe. - */ + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Acquire a command buffer. @@ -1437,10 +2766,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( * acquired on. The command buffer should be submitted on the thread it was * acquired on. * - * \param device a GPU context. - * \returns a command buffer. + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. * - * \since This function is available since SDL 3.0.0. + * \param device a GPU context. + * \returns a command buffer, or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence @@ -1448,118 +2785,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer( SDL_GPUDevice *device); -/* - * UNIFORM DATA - * - * Uniforms are for passing data to shaders. - * The uniform data will be constant across all executions of the shader. - * - * There are 4 available uniform slots per shader stage (vertex, fragment, compute). - * Uniform data pushed to a slot on a stage keeps its value throughout the command buffer - * until you call the relevant Push function on that slot again. - * - * For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, - * push the camera matrix at the start of the command buffer, and that data will be used for every - * subsequent draw call. - * - * It is valid to push uniform data during a render or compute pass. - * - * Uniforms are best for pushing small amounts of data. - * If you are pushing more than a matrix or two per call you should consider using a storage buffer instead. - */ +/* Uniform Data */ /** * Pushes data to a vertex uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the vertex uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the vertex uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a fragment uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the fragment uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the fragment uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); - -/* - * A NOTE ON CYCLING - * - * When using a command buffer, operations do not occur immediately - - * they occur some time after the command buffer is submitted. - * - * When a resource is used in a pending or active command buffer, it is considered to be "bound". - * When a resource is no longer used in any pending or active command buffers, it is considered to be "unbound". - * - * If data resources are bound, it is unspecified when that data will be unbound - * unless you acquire a fence when submitting the command buffer and wait on it. - * However, this doesn't mean you need to track resource usage manually. - * - * All of the functions and structs that involve writing to a resource have a "cycle" bool. - * GPUTransferBuffer, GPUBuffer, and GPUTexture all effectively function as ring buffers on internal resources. - * When cycle is SDL_TRUE, if the resource is bound, the cycle rotates to the next unbound internal resource, - * or if none are available, a new one is created. - * This means you don't have to worry about complex state tracking and synchronization as long as cycling is correctly employed. - * - * For example: you can call MapTransferBuffer, write texture data, UnmapTransferBuffer, and then UploadToTexture. - * The next time you write texture data to the transfer buffer, if you set the cycle param to SDL_TRUE, you don't have - * to worry about overwriting any data that is not yet uploaded. - * - * Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. - * If you set cycle to SDL_TRUE in the ColorAttachmentInfo struct, you can prevent this data dependency. - * - * Cycling will never undefine already bound data. - * When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. - * You must take care not to read undefined data. - * - * Note that when cycling a texture, the entire texture will be cycled, - * even if only part of the texture is used in the call, - * so you must consider the entire texture to contain undefined data after cycling. - * - * You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. - * It is OK to overwrite unreferenced data in a bound resource without cycling, - * but overwriting a section of data that has already been referenced will produce unexpected results. - */ + Uint32 length); /* Graphics State */ @@ -1574,212 +2854,240 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( * is called. You cannot begin another render pass, or begin a compute pass or * copy pass until you have ended the render pass. * - * \param commandBuffer a command buffer. - * \param colorAttachmentInfos an array of texture subresources with - * corresponding clear values and load/store ops. - * \param colorAttachmentCount the number of color attachments in the - * colorAttachmentInfos array. - * \param depthStencilAttachmentInfo a texture subresource with corresponding - * clear value and load/store ops, may be - * NULL. + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. * \returns a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPURenderPass */ extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUColorAttachmentInfo *colorAttachmentInfos, - Uint32 colorAttachmentCount, - SDL_GPUDepthStencilAttachmentInfo *depthStencilAttachmentInfo); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); /** * Binds a graphics pipeline on a render pass to be used in rendering. * * A graphics pipeline must be bound before making any draw calls. * - * \param renderPass a render pass handle. - * \param graphicsPipeline the graphics pipeline to bind. + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( - SDL_GPURenderPass *renderPass, - SDL_GPUGraphicsPipeline *graphicsPipeline); + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Sets the current viewport state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param viewport the viewport to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( - SDL_GPURenderPass *renderPass, - SDL_GPUViewport *viewport); + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); /** * Sets the current scissor state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param scissor the scissor area to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( - SDL_GPURenderPass *renderPass, - SDL_Rect *scissor); + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); /** * Binds vertex buffers on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param firstBinding the starting bind point for the vertex buffers. - * \param pBindings an array of SDL_GPUBufferBinding structs containing vertex - * buffers and offset values. - * \param bindingCount the number of bindings in the pBindings array. + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstBinding, - SDL_GPUBufferBinding *pBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); /** * Binds an index buffer on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param pBinding a pointer to a struct containing an index buffer and - * offset. - * \param indexElementSize whether the index values in the buffer are 16- or - * 32-bit. + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( - SDL_GPURenderPass *renderPass, - SDL_GPUBufferBinding *pBinding, - SDL_GPUIndexElementSize indexElementSize); + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); /** * Binds texture-sampler pairs for use on the vertex shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the vertex sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the vertex shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage texture to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage texture to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the vertex shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage buffer slot to begin binding from. - * \param storageBuffers an array of buffers. - * \param bindingCount the number of buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage buffer slot to begin binding from. + * \param storage_buffers an array of buffers. + * \param num_bindings the number of buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Binds texture-sampler pairs for use on the fragment shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the fragment sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the fragment shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the fragment shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffers. - * \param bindingCount the number of storage buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffers. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /* Drawing */ @@ -1789,100 +3097,101 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param indexCount the number of vertices to draw per instance. - * \param instanceCount the number of instances to draw. - * \param firstIndex the starting index within the index buffer. - * \param vertexOffset value added to vertex index before indexing into the - * vertex buffer. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 indexCount, - Uint32 instanceCount, - Uint32 firstIndex, - Sint32 vertexOffset, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); /** * Draws data using bound graphics state. * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param vertexCount the number of vertices to draw. - * \param instanceCount the number of instances that will be drawn. - * \param firstVertex the index of the first vertex to draw. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 vertexCount, - Uint32 instanceCount, - Uint32 firstVertex, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); /** * Draws data using bound graphics state and with draw parameters set from a * buffer. * - * The buffer layout should match the layout of SDL_GPUIndirectDrawCommand. - * You must not call this function before binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Draws data using bound graphics state with an index buffer enabled and with * draw parameters set from a buffer. * - * The buffer layout should match the layout of - * SDL_GPUIndexedIndirectDrawCommand. You must not call this function before - * binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Ends the given render pass. @@ -1890,12 +3199,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( * All bound graphics state on the render pass command buffer is unset. The * render pass handle is now invalid. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( - SDL_GPURenderPass *renderPass); + SDL_GPURenderPass *render_pass); /* Compute Pass */ @@ -1903,89 +3212,115 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( * Begins a compute pass on a command buffer. * * A compute pass is defined by a set of texture subresources and buffers that - * will be written to by compute pipelines. These textures and buffers must - * have been created with the COMPUTE_STORAGE_WRITE bit. All operations - * related to compute pipelines must take place inside of a compute pass. You - * must not begin another compute pass, or a render pass or copy pass before - * ending the compute pass. + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. * - * A VERY IMPORTANT NOTE Textures and buffers bound as write-only MUST NOT be - * read from during the compute pass. Doing so will result in undefined - * behavior. If your compute work requires reading the output from a previous - * dispatch, you MUST end the current compute pass and begin a new one before - * you can safely access the data. + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! * - * \param commandBuffer a command buffer. - * \param storageTextureBindings an array of writeable storage texture binding - * structs. - * \param storageTextureBindingCount the number of storage textures to bind - * from the array. - * \param storageBufferBindings an array of writeable storage buffer binding - * structs. - * \param storageBufferBindingCount the number of storage buffers to bind from - * the array. + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. * \returns a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPUComputePass */ extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUStorageTextureWriteOnlyBinding *storageTextureBindings, - Uint32 storageTextureBindingCount, - SDL_GPUStorageBufferWriteOnlyBinding *storageBufferBindings, - Uint32 storageBufferBindingCount); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); /** * Binds a compute pipeline on a command buffer for use in compute dispatch. * - * \param computePass a compute pass handle. - * \param computePipeline a compute pipeline to bind. + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( - SDL_GPUComputePass *computePass, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler bindings to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures as readonly for use on the compute pipeline. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers as readonly for use on the compute pipeline. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffer binding structs. - * \param bindingCount the number of storage buffers to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffer binding structs. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Dispatches compute work. @@ -1997,21 +3332,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. - * \param groupCountX number of local workgroups to dispatch in the X - * dimension. - * \param groupCountY number of local workgroups to dispatch in the Y - * dimension. - * \param groupCountZ number of local workgroups to dispatch in the Z - * dimension. + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( - SDL_GPUComputePass *computePass, - Uint32 groupCountX, - Uint32 groupCountY, - Uint32 groupCountZ); + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); /** * Dispatches compute work with parameters set from a buffer. @@ -2025,16 +3360,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * \param buffer a buffer containing dispatch parameters. - * \param offsetInBytes the offset to start reading from the dispatch buffer. + * \param offset the offset to start reading from the dispatch buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( - SDL_GPUComputePass *computePass, + SDL_GPUComputePass *compute_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes); + Uint32 offset); /** * Ends the current compute pass. @@ -2042,12 +3377,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( * All bound compute state on the command buffer is unset. The compute pass * handle is now invalid. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( - SDL_GPUComputePass *computePass); + SDL_GPUComputePass *compute_pass); /* TransferBuffer Data */ @@ -2057,28 +3392,29 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( * You must unmap the transfer buffer before encoding upload commands. * * \param device a GPU context. - * \param transferBuffer a transfer buffer. - * \param cycle if SDL_TRUE, cycles the transfer buffer if it is bound. - * \returns the address of the mapped transfer buffer memory. + * \param transfer_buffer a transfer buffer. + * \param cycle if true, cycles the transfer buffer if it is already bound. + * \returns the address of the mapped transfer buffer memory, or NULL on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer, - SDL_bool cycle); + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); /** * Unmaps a previously mapped transfer buffer. * * \param device a GPU context. - * \param transferBuffer a previously mapped transfer buffer. + * \param transfer_buffer a previously mapped transfer buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /* Copy Pass */ @@ -2089,13 +3425,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( * inside a copy pass. You must not begin another copy pass, or a render pass * or compute pass before ending the copy pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \returns a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /** * Uploads data from a transfer buffer to a texture. @@ -2106,21 +3442,19 @@ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( * You must align the data in the transfer buffer to a multiple of the texel * size of the texture format. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with image layout information. * \param destination the destination texture region. - * \param cycle if SDL_TRUE, cycles the texture if the texture is bound, - * otherwise overwrites the data. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureTransferInfo *source, - SDL_GPUTextureRegion *destination, - SDL_bool cycle); - -/* Uploads data from a TransferBuffer to a Buffer. */ + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); /** * Uploads data from a transfer buffer to a buffer. @@ -2128,19 +3462,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( * The upload occurs on the GPU timeline. You may assume that the upload has * finished in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with offset. * \param destination the destination buffer with offset and size. - * \param cycle if SDL_TRUE, cycles the buffer if it is bound, otherwise + * \param cycle if true, cycles the buffer if it is already bound, otherwise * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUTransferBufferLocation *source, - SDL_GPUBufferRegion *destination, - SDL_bool cycle); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); /** * Performs a texture-to-texture copy. @@ -2148,27 +3482,25 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source a source texture region. * \param destination a destination texture region. * \param w the width of the region to copy. * \param h the height of the region to copy. * \param d the depth of the region to copy. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination + * \param cycle if true, cycles the destination texture if the destination * texture is bound, otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureLocation *source, - SDL_GPUTextureLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, Uint32 w, Uint32 h, Uint32 d, - SDL_bool cycle); - -/* Copies data from a buffer to a buffer. */ + bool cycle); /** * Performs a buffer-to-buffer copy. @@ -2176,21 +3508,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the buffer and offset to copy from. * \param destination the buffer and offset to copy to. * \param size the length of the buffer to copy. - * \param cycle if SDL_TRUE, cycles the destination buffer if it is bound, + * \param cycle if true, cycles the destination buffer if it is already bound, * otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferLocation *source, - SDL_GPUBufferLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, Uint32 size, - SDL_bool cycle); + bool cycle); /** * Copies data from a texture to a transfer buffer on the GPU timeline. @@ -2198,17 +3530,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source texture region. * \param destination the destination transfer buffer with image layout * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureRegion *source, - SDL_GPUTextureTransferInfo *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); /** * Copies data from a buffer to a transfer buffer on the GPU timeline. @@ -2216,39 +3548,39 @@ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source buffer with offset and size. * \param destination the destination transfer buffer with offset. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferRegion *source, - SDL_GPUTransferBufferLocation *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); /** * Ends the current copy pass. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( - SDL_GPUCopyPass *copyPass); + SDL_GPUCopyPass *copy_pass); /** * Generates mipmaps for the given texture. * * This function must not be called inside of any pass. * - * \param commandBuffer a commandBuffer. + * \param command_buffer a command_buffer. * \param texture a texture with more than 1 mip level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, SDL_GPUTexture *texture); /** @@ -2256,23 +3588,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( * * This function must not be called inside of any pass. * - * \param commandBuffer a command buffer. - * \param source the texture region to copy from. - * \param destination the texture region to copy to. - * \param flipMode the flip mode for the source texture region. - * \param filterMode the filter mode that will be used when blitting. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination - * texture is bound, otherwise overwrites the data. + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUBlitRegion *source, - SDL_GPUBlitRegion *destination, - SDL_FlipMode flipMode, - SDL_GPUFilter filterMode, - SDL_bool cycle); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); /* Submission/Presentation */ @@ -2283,17 +3606,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( * * \param device a GPU context. * \param window an SDL_Window. - * \param swapchainComposition the swapchain composition to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition); + SDL_GPUSwapchainComposition swapchain_composition); /** * Determines whether a presentation mode is supported by the window. @@ -2302,40 +3625,46 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( * * \param device a GPU context. * \param window an SDL_Window. - * \param presentMode the presentation mode to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUPresentMode presentMode); + SDL_GPUPresentMode present_mode); /** * Claims a window, creating a swapchain structure for it. * * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created * the window. * * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain - * parameters, you must call SetSwapchainParameters after claiming the window. + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. * * \param device a GPU context. * \param window an SDL_Window. - * \returns SDL_TRUE on success, otherwise SDL_FALSE. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. * - * \sa SDL_AcquireGPUSwapchainTexture + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_ReleaseWindowFromGPUDevice * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( SDL_GPUDevice *device, SDL_Window *window); @@ -2345,7 +3674,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( * \param device a GPU context. * \param window an SDL_Window that has been claimed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ @@ -2366,29 +3695,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( * * \param device a GPU context. * \param window an SDL_Window that has been claimed. - * \param swapchainComposition the desired composition of the swapchain. - * \param presentMode the desired present mode for the swapchain. - * \returns SDL_TRUE if successful, SDL_FALSE on error. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGPUSwapchainParameters( +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition, - SDL_GPUPresentMode presentMode); + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture pointer with NULL, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight( + SDL_GPUDevice *device, + Uint32 allowed_frames_in_flight); /** * Obtains the texture format of the swapchain for the given window. * + * Note that this format can change if the swapchain parameters change. + * * \param device a GPU context. * \param window an SDL_Window that has been claimed. * \returns the texture format of the swapchain. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( SDL_GPUDevice *device, @@ -2400,28 +3761,118 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma * When a swapchain texture is acquired on a command buffer, it will * automatically be submitted for presentation when the command buffer is * submitted. The swapchain texture should only be referenced by the command - * buffer used to acquire it. May return NULL under certain conditions. This - * is not necessarily an error. This texture is managed by the implementation - * and must not be freed by the user. You MUST NOT call this function from any - * thread other than the one that created the window. + * buffer used to acquire it. * - * \param commandBuffer a command buffer. + * This function will fill the swapchain texture handle with NULL if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. * \param window a window that has been claimed. - * \param pWidth a pointer filled in with the swapchain width. - * \param pHeight a pointer filled in with the swapchain height. - * \returns a swapchain texture. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight */ -extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( - SDL_GPUCommandBuffer *commandBuffer, +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, SDL_Window *window, - Uint32 *pWidth, - Uint32 *pHeight); + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with NULL in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the pointer is NULL before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); /** * Submits a command buffer so its commands can be processed on the GPU. @@ -2433,16 +3884,19 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( - SDL_GPUCommandBuffer *commandBuffer); +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Submits a command buffer so its commands can be processed on the GPU, and @@ -2456,63 +3910,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. - * \returns a fence associated with the command buffer. + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_ReleaseGPUFence */ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); + +/** + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Blocks the thread until the GPU is completely idle. * * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitForGPUFences */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUIdle( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( SDL_GPUDevice *device); /** * Blocks the thread until the given fences are signaled. * * \param device a GPU context. - * \param waitAll if 0, wait for any fence to be signaled, if 1, wait for all - * fences to be signaled. - * \param pFences an array of fences to wait on. - * \param fenceCount the number of fences in the pFences array. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence * \sa SDL_WaitForGPUIdle */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUFences( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( SDL_GPUDevice *device, - SDL_bool waitAll, - SDL_GPUFence **pFences, - Uint32 fenceCount); + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); /** * Checks the status of a fence. * * \param device a GPU context. * \param fence a fence. - * \returns SDL_TRUE if the fence is signaled, SDL_FALSE if it is not. + * \returns true if the fence is signaled, false if it is not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( SDL_GPUDevice *device, SDL_GPUFence *fence); @@ -2522,7 +4007,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( * \param device a GPU context. * \param fence a fence. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ @@ -2535,15 +4020,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( /** * Obtains the texel block size for a texture format. * - * \param textureFormat the texture format you want to know the texel size of. + * \param format the texture format you want to know the texel size of. * \returns the texel block size of the texture format. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( - SDL_GPUTextureFormat textureFormat); + SDL_GPUTextureFormat format); /** * Determines whether a texture format is supported for a given type and @@ -2555,9 +4040,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( * \param usage a bitmask of all usage scenarios to check. * \returns whether the texture format is supported for this type and usage. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( SDL_GPUDevice *device, SDL_GPUTextureFormat format, SDL_GPUTextureType type, @@ -2568,15 +4053,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( * * \param device a GPU context. * \param format the texture format to check. - * \param sampleCount the sample count to check. + * \param sample_count the sample count to check. * \returns a hardware-specific version of min(preferred, possible). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( SDL_GPUDevice *device, SDL_GPUTextureFormat format, - SDL_GPUSampleCount sampleCount); + SDL_GPUSampleCount sample_count); + +/** + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize( + SDL_GPUTextureFormat format, + Uint32 width, + Uint32 height, + Uint32 depth_or_layer_count); #ifdef SDL_PLATFORM_GDK @@ -2589,7 +4091,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -2604,7 +4106,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_guid.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_guid.h index 285b237..e2f32ff 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_guid.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_guid.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,13 +26,14 @@ * * A GUID is a 128-bit value that represents something that is uniquely * identifiable by this value: "globally unique." + * + * SDL provides functions to convert a GUID to/from a string. */ #ifndef SDL_guid_h_ #define SDL_guid_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -55,7 +56,7 @@ extern "C" { * GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs on different operating systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GUID { Uint8 data[16]; @@ -70,7 +71,7 @@ typedef struct SDL_GUID { * \param pszGUID buffer in which to write the ASCII string. * \param cbGUID the size of pszGUID, should be at least 33 bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StringToGUID */ @@ -86,7 +87,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_GUID structure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_haptic.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_haptic.h index 95446fe..a45335b 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_haptic.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_haptic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -66,7 +66,7 @@ * Complete example: * * ```c - * SDL_bool test_haptic(SDL_Joystick *joystick) + * bool test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -74,12 +74,12 @@ * * // Open the device * haptic = SDL_OpenHapticFromJoystick(joystick); - * if (haptic == NULL) return SDL_FALSE; // Most likely joystick isn't haptic + * if (haptic == NULL) return false; // Most likely joystick isn't haptic * * // See if it can do sine waves * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) { * SDL_CloseHaptic(haptic); // No sine effect - * return SDL_FALSE; + * return false; * } * * // Create the effect @@ -106,7 +106,7 @@ * // Close the device * SDL_CloseHaptic(haptic); * - * return SDL_TRUE; // Success + * return true; // Success * } * ``` * @@ -139,15 +139,14 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_OpenHaptic - * \sa SDL_OpenHapticFromJoystick - * \sa SDL_CloseHaptic + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct SDL_Haptic; typedef struct SDL_Haptic SDL_Haptic; @@ -168,7 +167,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Constant haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -179,7 +178,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates sine waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -190,7 +189,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates square waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -201,7 +200,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates triangular waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -212,7 +211,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth up waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -223,7 +222,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth down waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -234,7 +233,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Ramp haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticRamp */ @@ -246,7 +245,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates a spring. Effect is based on the * axes position. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -258,7 +257,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -270,7 +269,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -282,7 +281,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates friction. Effect is based on the * axes movement. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -293,19 +292,31 @@ typedef struct SDL_Haptic SDL_Haptic; * * Haptic effect for direct control over high/low frequency motors. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** @@ -313,7 +324,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * User defined custom haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_CUSTOM (1u<<15) @@ -326,7 +337,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting the global gain. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticGain */ @@ -337,7 +348,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting autocenter. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticAutocenter */ @@ -348,7 +359,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports querying effect status. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus */ @@ -359,7 +370,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Devices supports being paused. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_PauseHaptic * \sa SDL_ResumeHaptic @@ -375,7 +386,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses polar coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -384,7 +395,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses cartesian coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -393,7 +404,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses spherical coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -405,7 +416,7 @@ typedef struct SDL_Haptic SDL_Haptic; * This provides better compatibility across platforms and devices as SDL will * guess the correct axis. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -422,7 +433,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Used to play a device an infinite number of times. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect */ @@ -523,7 +534,7 @@ typedef struct SDL_Haptic SDL_Haptic; * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN @@ -547,7 +558,7 @@ typedef struct SDL_HapticDirection * A constant effect applies a constant force in the specified direction to * the joystick. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect @@ -629,7 +640,7 @@ typedef struct SDL_HapticConstant * \| \| \| \| \| \| \| * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE @@ -685,7 +696,7 @@ typedef struct SDL_HapticPeriodic * SDL_HapticDirection diagram for which side is positive and which is * negative. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticDirection * \sa SDL_HAPTIC_SPRING @@ -699,7 +710,7 @@ typedef struct SDL_HapticCondition /* Header */ Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -728,7 +739,7 @@ typedef struct SDL_HapticCondition * effects get added to the ramp effect making the effect become quadratic * instead of linear. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect @@ -767,7 +778,7 @@ typedef struct SDL_HapticRamp * motors, commonly found in modern game controllers. The small (right) motor * is high frequency, and the large (left) motor is low frequency. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HapticEffect @@ -797,7 +808,7 @@ typedef struct SDL_HapticLeftRight * If channels is one, the effect is rotated using the defined direction. * Otherwise it uses the samples in data for the different axes. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CUSTOM * \sa SDL_HapticEffect @@ -892,7 +903,7 @@ typedef struct SDL_HapticCustom * Note either the attack_level or the fade_level may be above the actual * effect level. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic @@ -921,7 +932,7 @@ typedef union SDL_HapticEffect * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_HapticID; @@ -937,7 +948,7 @@ typedef Uint32 SDL_HapticID; * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -953,7 +964,7 @@ extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticName * \sa SDL_OpenHaptic @@ -974,7 +985,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID ins * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_GetHaptics @@ -993,7 +1004,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id); @@ -1004,7 +1015,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instan * \returns the instance ID of the specified haptic device on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); @@ -1016,7 +1027,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticNameForID */ @@ -1025,13 +1036,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromMouse */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -1039,7 +1050,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); * \returns the haptic device identifier or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsMouseHaptic @@ -1050,13 +1061,13 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. + * \returns true if the joystick is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -1073,7 +1084,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick * \returns a valid haptic device identifier on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsJoystickHaptic @@ -1085,7 +1096,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick * * \param haptic the SDL_Haptic device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -1102,7 +1113,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic); * \returns the number of effects the haptic device can store or a negative * error code on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffectsPlaying * \sa SDL_GetHapticFeatures @@ -1118,7 +1129,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); * \returns the number of effects the haptic device can play at the same time * or -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffects * \sa SDL_GetHapticFeatures @@ -1132,7 +1143,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HapticEffectSupported * \sa SDL_GetMaxHapticEffects @@ -1149,7 +1160,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); * \returns the number of axes on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); @@ -1158,14 +1169,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1176,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti * \returns the ID of the effect on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyHapticEffect * \sa SDL_RunHapticEffect @@ -1196,15 +1207,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_RunHapticEffect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1219,31 +1230,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus * \sa SDL_StopHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1254,7 +1265,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, in * \param haptic the SDL_Haptic device to destroy the effect on. * \param effect the ID of the haptic effect to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect */ @@ -1267,14 +1278,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns SDL_TRUE if it is playing, SDL_FALSE if it isn't playing or haptic - * status isn't supported. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1289,14 +1300,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *hapti * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1308,14 +1319,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int g * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. @@ -1327,14 +1338,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** * Resume a haptic device. @@ -1342,55 +1353,55 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1398,28 +1409,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble * \sa SDL_StopHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hidapi.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hidapi.h index 66bea9d..131b037 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hidapi.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hidapi.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -65,14 +65,14 @@ extern "C" { /** * An opaque handle representing an open HID device. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device SDL_hid_device; /** * HID underlying bus types. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_hid_bus_type { /** Unknown bus type */ @@ -107,7 +107,7 @@ typedef enum SDL_hid_bus_type { /** * Information about a connected HID device * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device_info { @@ -169,7 +169,7 @@ typedef struct SDL_hid_device_info * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_exit */ @@ -184,7 +184,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_init */ @@ -205,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void); * \returns a change counter that is incremented with each potential device * change, or 0 if device change detection isn't available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_enumerate */ @@ -233,7 +233,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); * in the case of failure. Free this linked list by calling * SDL_hid_free_enumeration(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_device_change_count */ @@ -247,7 +247,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho * \param devs pointer to a list of struct_device returned from * SDL_hid_enumerate(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); @@ -265,7 +265,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); @@ -279,7 +279,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_ * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); @@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path) * \returns the actual number of bytes written and -1 on on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne * SDL_GetError() for more information. If no packet was available to * be read within the timeout period, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); @@ -348,7 +348,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign * be read and the handle is in non-blocking mode, this function * returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -367,7 +367,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); @@ -392,7 +392,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int * \returns the actual number of bytes written and -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -415,7 +415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -438,7 +438,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -449,7 +449,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); @@ -462,7 +462,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device * * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -488,7 +488,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -502,7 +502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); @@ -514,7 +514,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, * on failure; call SDL_GetError() for more information. This struct * is valid until the device is closed with SDL_hid_close(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); @@ -530,18 +530,18 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi * \returns the number of bytes actually copied or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. + * \param active true to start the scan, false to stop the scan. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hints.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hints.h index 8433240..8f2d074 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hints.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_hints.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,8 +22,6 @@ /** * # CategoryHints * - * Official documentation for SDL configuration variables - * * This file contains functions to set and get configuration hints, as well as * listing each of them alphabetically. * @@ -63,7 +61,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" @@ -83,7 +81,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" @@ -98,10 +96,27 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" +/** + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" + /** * A variable to control whether we trap the Android back button to handle it * manually. @@ -121,7 +136,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" @@ -137,7 +152,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_ID "SDL_APP_ID" @@ -155,7 +170,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_NAME "SDL_APP_NAME" @@ -178,7 +193,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" @@ -193,7 +208,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" @@ -201,16 +216,58 @@ extern "C" { * Specify the default ALSA audio device name. * * This variable is a specific audio device to open when the "default" audio - * device is used. By default if 4 channel audio is requested, the - * "plug:surround40" device will be opened and if 6 channel audio is requested - * the "plug:surround51" device will be opened. + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE */ #define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" +/** + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" + +/** + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" + /** * A variable controlling the audio category on iOS and macOS. * @@ -225,7 +282,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" @@ -238,7 +295,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" @@ -261,7 +318,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" @@ -283,7 +340,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" @@ -310,7 +367,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" @@ -336,7 +393,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" @@ -347,7 +404,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" @@ -358,7 +415,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" @@ -371,7 +428,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" @@ -385,7 +442,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" @@ -398,7 +455,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" @@ -409,18 +466,23 @@ extern "C" { * device, this hint can be used to specify a default format that will be * used. * - * The variable can be set to the following values: - "U8": Unsigned 8-bit - * audio - "S8": Signed 8-bit audio - "S16LE": Signed 16-bit little-endian - * audio - "S16BE": Signed 16-bit big-endian audio - "S16": Signed 16-bit - * native-endian audio (default) - "S32LE": Signed 32-bit little-endian audio - * - "S32BE": Signed 32-bit big-endian audio - "S32": Signed 32-bit - * native-endian audio - "F32LE": Floating point little-endian audio - - * "F32BE": Floating point big-endian audio - "F32": Floating point - * native-endian audio + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" @@ -433,7 +495,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" @@ -456,7 +518,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" @@ -471,7 +533,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" @@ -486,7 +548,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" @@ -509,7 +571,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" @@ -525,7 +587,7 @@ extern "C" { * best camera backend on your behalf. This hint needs to be set before * SDL_Init() is called to be useful. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" @@ -558,7 +620,7 @@ extern "C" { * * The items can be prefixed by '+'/'-' to add/remove features. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" @@ -572,7 +634,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" @@ -601,7 +663,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" @@ -619,7 +681,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" @@ -640,7 +702,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" @@ -653,7 +715,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" @@ -668,12 +730,13 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all * - any other string without a leading # sign applies to the element on the * page with that ID. * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" @@ -690,7 +753,7 @@ extern "C" { * * This hint must be set before SDL_StartTextInput() is called * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" @@ -707,7 +770,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" @@ -731,7 +794,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" @@ -751,7 +814,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" @@ -772,7 +835,7 @@ extern "C" { * * This hint should be set before calling SDL_GetWindowSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" @@ -787,7 +850,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" @@ -803,7 +866,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" @@ -827,7 +890,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" @@ -845,7 +908,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" @@ -863,7 +926,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" @@ -886,7 +949,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" @@ -898,7 +961,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" @@ -910,7 +973,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" @@ -925,7 +988,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" @@ -941,7 +1004,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" @@ -952,7 +1015,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" @@ -970,7 +1033,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" @@ -988,7 +1051,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" @@ -1002,7 +1065,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" @@ -1011,12 +1074,12 @@ extern "C" { * * By default, SDL will try all available GPU backends in a reasonable order * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "d3d11" if, say, your hardware supports - * D3D12 but want to try using D3D11 instead. + * force a specific target, such as "direct3d11" if, say, your hardware + * supports D3D12 but want to try using D3D11 instead. * - * This hint should be set before SDL_GPUSelectBackend() is called. + * This hint should be set before any GPU functions are called. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" @@ -1035,7 +1098,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" @@ -1052,7 +1115,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" @@ -1075,7 +1138,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" @@ -1094,7 +1157,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" @@ -1111,7 +1174,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" @@ -1128,7 +1191,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" @@ -1149,7 +1212,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" @@ -1167,7 +1230,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" @@ -1188,7 +1251,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" @@ -1198,10 +1261,35 @@ extern "C" { * * This variable is currently only used by the Linux joystick driver. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" +/** + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" + /** * A variable containing a list of flightstick style controllers. * @@ -1215,7 +1303,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" @@ -1236,7 +1324,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" @@ -1246,12 +1334,14 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": GameInput is not used. (default) + * - "0": GameInput is not used. * - "1": GameInput is used. * + * The default is "1" on GDK platforms, and "0" otherwise. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" @@ -1269,7 +1359,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" @@ -1290,7 +1380,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" @@ -1305,9 +1395,9 @@ extern "C" { * This variable is the default for all drivers, but can be overridden by the * hints for specific drivers below. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" @@ -1322,9 +1412,9 @@ extern "C" { * - "1": Left and right Joy-Con controllers will be combined into a single * controller. (default) * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" @@ -1339,9 +1429,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" @@ -1362,7 +1452,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" @@ -1377,9 +1467,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" @@ -1398,7 +1488,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" @@ -1413,9 +1503,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" @@ -1430,9 +1520,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" @@ -1452,9 +1542,9 @@ extern "C" { * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" @@ -1469,9 +1559,9 @@ extern "C" { * * The default value is 0. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" @@ -1486,9 +1576,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" @@ -1503,36 +1593,10 @@ extern "C" { * This hint can be set anytime, but only takes effect when extended input * reports are enabled. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" -/** - * A variable controlling whether extended input reports should be used for - * PS4 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports are enabled. - * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value will also control - * the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for PS5 controllers should * be used. @@ -1544,9 +1608,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" @@ -1559,35 +1623,10 @@ extern "C" { * - "0": player LEDs are not enabled. * - "1": player LEDs are enabled. (default) * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" -/** - * A variable controlling whether extended input reports should be used for - * PS5 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports. - * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value defaults to the - * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD * controllers should be used. @@ -1599,9 +1638,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" @@ -1616,7 +1655,7 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" @@ -1631,12 +1670,31 @@ extern "C" { * Bluetooth access and may prompt the user for permission on iOS and * Android. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" +/** + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" + /** * A variable controlling whether the HIDAPI driver for the Steam Deck builtin * controller should be used. @@ -1648,12 +1706,23 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + /** * A variable controlling whether the HIDAPI driver for Nintendo Switch * controllers should be used. @@ -1665,9 +1734,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" @@ -1686,7 +1755,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" @@ -1701,7 +1770,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" @@ -1717,7 +1786,7 @@ extern "C" { * * This hint should be set before opening a Joy-Con controller. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" @@ -1730,12 +1799,12 @@ extern "C" { * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. + * This driver doesn't work with the dolphinbar, so the default is false for + * now. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" @@ -1750,7 +1819,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" @@ -1766,9 +1835,9 @@ extern "C" { * The default is "0" on Windows, otherwise the value of * SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" @@ -1783,9 +1852,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" @@ -1800,7 +1869,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" @@ -1815,9 +1884,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" @@ -1832,9 +1901,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" @@ -1853,7 +1922,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" @@ -1868,7 +1937,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" @@ -1883,7 +1952,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" @@ -1898,7 +1967,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" @@ -1916,7 +1985,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" @@ -1932,7 +2001,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" @@ -1947,7 +2016,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" @@ -1962,7 +2031,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" @@ -1979,7 +2048,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" @@ -1994,7 +2063,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" @@ -2004,12 +2073,12 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": A separate thread is not used. (default) - * - "1": A separate thread is used for handling raw input messages. + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" @@ -2026,7 +2095,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" @@ -2047,7 +2116,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" @@ -2062,7 +2131,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" @@ -2079,7 +2148,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" @@ -2100,7 +2169,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" @@ -2118,7 +2187,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" @@ -2139,7 +2208,7 @@ extern "C" { * - "latin_letters": For keyboards using non-Latin letters, such as Russian * or Thai, the letter keys generate keycodes as though it had an en_US * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian - * keyboard would yield 'a' instead of 'ф'. + * keyboard would yield 'a' instead of a Cyrillic letter. * * The default value for this hint is "french_numbers,latin_letters" * @@ -2152,7 +2221,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" @@ -2166,7 +2235,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" @@ -2194,7 +2263,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" @@ -2220,7 +2289,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_LOGGING "SDL_LOGGING" @@ -2234,9 +2303,9 @@ extern "C" { * (default) * - "1": The application may remain in the background when launched. * - * This hint should be set before applicationDidFinishLaunching() is called. + * This hint needs to be set before SDL_Init(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" @@ -2252,7 +2321,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" @@ -2275,25 +2344,73 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" +/** + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + +/** + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" + /** * Request SDL_AppIterate() be called at a specific rate. * - * This number is in Hz, so "60" means try to iterate 60 times per second. + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. * * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, * this hint is ignored. When the hint can be used, it is allowed to be * changed at any time. * - * This defaults to 60, and specifying NULL for the hint's value will restore + * This defaults to 0, and specifying NULL for the hint's value will restore * the default. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" @@ -2312,7 +2429,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" @@ -2321,7 +2438,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" @@ -2330,10 +2447,22 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" +/** + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" + /** * A variable controlling whether warping a hidden mouse cursor will activate * relative mouse mode. @@ -2362,7 +2491,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" @@ -2376,7 +2505,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" @@ -2386,7 +2515,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" @@ -2407,32 +2536,17 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" -/** - * A variable controlling whether relative mouse mode is implemented using - * mouse warping. - * - * The variable can be set to the following values: - * - * - "0": Relative mouse mode uses raw input. (default) - * - "1": Relative mouse mode uses mouse warping. - * - * This hint can be set anytime relative mode is not currently enabled. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" - /** * A variable setting the scale for mouse motion, in floating point, when the * mouse is in relative mode. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" @@ -2446,12 +2560,12 @@ extern "C" { * - "1": Relative mouse motion will be scaled using the system mouse * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after * system speed scale. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" @@ -2470,7 +2584,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" @@ -2478,9 +2592,10 @@ extern "C" { * A variable controlling whether the hardware cursor stays visible when * relative mode is active. * - * This variable can be set to the following values: "0" - The cursor will be - * hidden while relative mode is active (default) "1" - The cursor will remain - * visible while relative mode is active + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active * * Note that for systems without raw hardware inputs, relative mode is * implemented using warping, so the hardware cursor will visibly warp between @@ -2488,27 +2603,10 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" -/** - * Controls how often SDL issues cursor confinement commands to the operating - * system while relative mode is active, in case the desired confinement state - * became out-of-sync due to interference from other running programs. - * - * The variable can be integers representing miliseconds between each refresh. - * A value of zero means SDL will not automatically refresh the confinement. - * The default value varies depending on the operating system, this variable - * might not have any effects on inapplicable platforms such as those without - * a cursor. - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" - /** * A variable controlling whether mouse events should generate synthetic touch * events. @@ -2522,7 +2620,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" @@ -2540,7 +2638,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" @@ -2555,7 +2653,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" @@ -2563,12 +2661,25 @@ extern "C" { * Specify the OpenGL library to load. * * This hint should be set before creating an OpenGL window or creating an - * OpenGL context. + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" +/** + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" + /** * A variable controlling what driver to use for OpenGL ES contexts. * @@ -2599,10 +2710,22 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" + /** * A variable controlling which orientations are allowed on iOS/Android. * @@ -2618,7 +2741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" @@ -2638,7 +2761,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" @@ -2656,7 +2779,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" @@ -2673,9 +2796,13 @@ extern "C" { * - "1": SDL will send a quit event when the last window is requesting to * close. (default) * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" @@ -2690,7 +2817,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" @@ -2706,7 +2833,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" @@ -2720,7 +2847,7 @@ extern "C" { * * By default, SDL does not use Vulkan Validation Layers. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" @@ -2734,7 +2861,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" @@ -2749,7 +2876,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" @@ -2758,7 +2885,7 @@ extern "C" { * * If the application doesn't pick a specific renderer to use, this variable * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * can't be initialized, creating a renderer will fail. * * This variable is case insensitive and can be set to the following values: * @@ -2770,14 +2897,19 @@ extern "C" { * - "opengles" * - "metal" * - "vulkan" + * - "gpu" * - "software" * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * * The default varies by platform, but it's the first one in the list that is * available on the current platform. * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" @@ -2795,7 +2927,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" @@ -2810,7 +2942,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" @@ -2827,7 +2959,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" @@ -2844,7 +2976,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" @@ -2861,7 +2993,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. * * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED */ @@ -2883,7 +3015,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" @@ -2895,7 +3027,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" @@ -2917,7 +3049,7 @@ extern "C" { * * This hint should be set before calling SDL_DisableScreenSaver() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" @@ -2936,7 +3068,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" @@ -2950,7 +3082,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" @@ -2964,7 +3096,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" @@ -2991,32 +3123,32 @@ extern "C" { * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling * policy * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** * A string specifying additional information to use with - * SDL_SetThreadPriority. + * SDL_SetCurrentThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. * * pthread hint values are "current", "other", "fifo" and "rr". Currently no * other platform hint values are defined but may be in the future. * * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the * distro configured execution budget for rtkit. This budget can be queried - * through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" @@ -3036,7 +3168,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" @@ -3051,7 +3183,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" @@ -3072,7 +3204,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -3087,7 +3219,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" @@ -3101,10 +3233,35 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" +/** + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" + /** * Tell the video driver that we only want a double buffer. * @@ -3124,7 +3281,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" @@ -3136,9 +3293,13 @@ extern "C" { * force a specific target, such as "x11" if, say, you are on Wayland but want * to try talking to the X server instead. * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" @@ -3151,7 +3312,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" @@ -3165,7 +3326,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" @@ -3181,7 +3342,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" @@ -3199,10 +3360,31 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + /** * A variable controlling whether fullscreen windows are minimized when they * lose focus. @@ -3215,7 +3397,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" @@ -3232,7 +3414,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" @@ -3258,7 +3440,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" @@ -3276,7 +3458,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" @@ -3296,7 +3478,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" @@ -3318,7 +3500,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" @@ -3338,7 +3520,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" @@ -3357,6 +3539,8 @@ extern "C" { * * - Rounding errors can result with odd window sizes and/or desktop scales, * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. * - The window may be unusably small on scaled desktops. * - The window may jump in size when moving between displays of different * scale factors. @@ -3375,7 +3559,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" @@ -3397,7 +3581,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" @@ -3412,7 +3596,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" @@ -3431,7 +3615,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" @@ -3445,7 +3629,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" @@ -3456,7 +3640,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" @@ -3465,7 +3649,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" @@ -3474,7 +3658,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" @@ -3488,7 +3672,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" @@ -3503,7 +3687,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" @@ -3518,7 +3702,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" @@ -3529,7 +3713,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" @@ -3542,7 +3726,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" @@ -3557,7 +3741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" @@ -3572,7 +3756,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" @@ -3588,7 +3772,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" @@ -3599,7 +3783,7 @@ extern "C" { * * This hint should be set before calling SDL_Vulkan_CreateSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" @@ -3609,7 +3793,7 @@ extern "C" { * This hint should be set before creating a Vulkan window or calling * SDL_Vulkan_LoadLibrary(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" @@ -3641,7 +3825,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" @@ -3653,7 +3837,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" @@ -3681,7 +3865,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" @@ -3701,7 +3885,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" @@ -3718,7 +3902,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" @@ -3735,7 +3919,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" @@ -3753,7 +3937,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" @@ -3769,7 +3953,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" @@ -3785,7 +3969,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" @@ -3814,7 +3998,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" @@ -3829,7 +4013,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" @@ -3845,7 +4029,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" @@ -3859,7 +4043,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" @@ -3880,7 +4064,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" @@ -3890,9 +4074,18 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** @@ -3917,7 +4110,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" @@ -3934,123 +4127,10 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" -/** - * A variable controlling whether back-button-press events on Windows Phone to - * be marked as handled. - * - * Windows Phone devices typically feature a Back button. When pressed, the OS - * will emit back-button-press events, which apps are expected to handle in an - * appropriate manner. If apps do not explicitly mark these events as - * 'Handled', then the OS will invoke its default behavior for unhandled - * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate - * the app (and attempt to switch to the previous app, or to the device's home - * screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to - * mark back-button-press events as Handled, if and when one is sent to the - * app. - * - * Internally, Windows Phone sends back button events as parameters to special - * back-button-press callback functions. Apps that need to respond to - * back-button-press events are expected to register one or more callback - * functions for such, shortly after being launched (during the app's - * initialization phase). After the back button is pressed, the OS will invoke - * these callbacks. If the app's callback(s) do not explicitly mark the event - * as handled by the time they return, or if the app never registers one of - * these callback, the OS will consider the event un-handled, and it will - * apply its default back button behavior (terminate the app). - * - * SDL registers its own back-button-press callback with the Windows Phone OS. - * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN - * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after - * which it will check the contents of the hint, - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the - * back button event's Handled property will get set to 'true'. If the hint's - * value is set to something else, or if it is unset, SDL will leave the - * event's Handled property alone. (By default, the OS sets this property to - * 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for - * either event type is suitable.) Any value of - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied - * to the OS' current back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found at - * the following page, on Microsoft's developer site: - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** - * A variable specifying the label text for a WinRT app's privacy policy link. - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, - * 8.1, and RT, Microsoft mandates that this policy be available via the - * Windows Settings charm. SDL provides code to add a link there, with its - * label text being set via the optional hint, - * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A - * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the - * actual text of the policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". - * - * For additional information on linking to a privacy policy, see the - * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. - * - * This hint should be set before SDL is initialized. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A variable specifying the URL to a WinRT app's privacy policy. - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - /** * A variable controlling whether X11 windows are marked as override-redirect. * @@ -4068,7 +4148,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" @@ -4085,18 +4165,18 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** * Specify the XCB library to load for the X11 driver. * - * This defaults to "libX11-xcb.so" + * The default is platform-specific, often "libX11-xcb.so.1". * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" @@ -4111,7 +4191,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" @@ -4135,15 +4215,45 @@ extern "C" { * This hint should be set before an assertion failure is triggered and can be * changed at any time. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ASSERT "SDL_ASSERT" +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + /** * An enumeration of hint priorities. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_HintPriority { @@ -4162,18 +4272,18 @@ typedef enum SDL_HintPriority * \param name the hint to set. * \param value the value of the hint variable. * \param priority the SDL_HintPriority level for the hint. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); /** * Set a hint with normal priority. @@ -4184,18 +4294,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, c * * \param name the hint to set. * \param value the value of the hint variable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); /** * Reset a hint to the default value. @@ -4205,17 +4315,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *v * change. * * \param name the hint to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_ResetHints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); /** * Reset all hints to the default values. @@ -4226,7 +4336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetHint */ @@ -4245,7 +4355,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); * callback instead is always thread-safe, as SDL holds a lock * on the thread subsystem during the callback. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_SetHintWithPriority @@ -4262,12 +4372,12 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); /** * A callback used to send notifications of hint value changes. @@ -4284,7 +4394,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo * hint value. SDL holds a lock on the hint subsystem when * calling this callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ @@ -4300,16 +4410,16 @@ typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * \param callback An SDL_HintCallback function that will be called when the * hint value changes. * \param userdata a pointer to pass to the callback function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveHintCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); /** * Remove a function watching a particular hint. @@ -4321,7 +4431,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_H * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_init.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_init.h index 5a13947..adf0de8 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_init.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_init.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,10 +22,30 @@ /** * # CategoryInit * - * SDL subsystem init and quit functions. + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). */ - #ifndef SDL_init_h_ #define SDL_init_h_ @@ -47,7 +67,7 @@ extern "C" { * These are the flags which may be passed to SDL_Init(). You should specify * the subsystems which you will be using in your application. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -57,9 +77,8 @@ extern "C" { */ typedef Uint32 SDL_InitFlags; -#define SDL_INIT_TIMER 0x00000001u #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ -#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */ #define SDL_INIT_HAPTIC 0x00001000u #define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ @@ -85,7 +104,7 @@ typedef Uint32 SDL_InitFlags; * [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. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AppResult { @@ -94,10 +113,70 @@ typedef enum SDL_AppResult SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ } SDL_AppResult; +/** + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); + +/** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ 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); + +/** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); + +/** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. @@ -117,11 +196,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * * `flags` may be any of the following OR'd together: * - * - `SDL_INIT_TIMER`: timer subsystem * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem + * subsystem, should be initialized on the main thread. * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem @@ -143,10 +221,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * SDL_SetAppMetadataProperty(). * * \param flags subsystem initialization flags. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty @@ -155,7 +233,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * \sa SDL_SetMainReady * \sa SDL_WasInit */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Init(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); /** * Compatibility function to initialize the SDL library. @@ -163,16 +241,16 @@ extern SDL_DECLSPEC SDL_bool 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit * \sa SDL_QuitSubSystem */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); /** * Shut down specific SDL subsystems. @@ -182,7 +260,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem * \sa SDL_Quit @@ -196,7 +274,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_InitSubSystem @@ -214,13 +292,70 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); * application is shutdown, but it is not wise to do this from a library or * other dynamically loaded code. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_QuitSubSystem */ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); +/** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void); + +/** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata); + +/** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete); + /** * Specify basic metadata about your app. * @@ -248,16 +383,16 @@ 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadataProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); /** * Specify metadata about your app through a set of properties. @@ -274,7 +409,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * Multiple calls to this function are allowed, but various state might not * change once it has been set up with a previous call to this function. * - * Once set, this metadata can be read using SDL_GetMetadataProperty(). + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). * * These are the supported properties: * @@ -310,17 +445,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * * \param name the name of the metadata property to set. * \param value the value of the property, or NULL to remove that property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); +extern SDL_DECLSPEC 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" @@ -346,7 +481,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name * freed if you call SDL_SetAppMetadataProperty() to set that * property from another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_intrin.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_intrin.h index efba11d..bac6d7a 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_intrin.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_intrin.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -19,8 +19,31 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * Header file for CPU intrinsics for SDL +/* WIKI CATEGORY: Intrinsics */ + +/** + * # CategoryIntrinsics + * + * SDL does some preprocessor gymnastics to determine if any CPU-specific + * compiler intrinsics are available, as this is not necessarily an easy thing + * to calculate, and sometimes depends on quirks of a system, versions of + * build tools, and other external forces. + * + * Apps including SDL's headers will be able to check consistent preprocessor + * definitions to decide if it's safe to use compiler intrinsics for a + * specific CPU architecture. This check only tells you that the compiler is + * capable of using those intrinsics; at runtime, you should still check if + * they are available on the current system with the + * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo) + * , such as SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash + * for using an unsupported CPU instruction. + * + * SDL only sets preprocessor defines for CPU intrinsics if they are + * supported, so apps should check with `#ifdef` and not `#if`. + * + * SDL will also include the appropriate instruction-set-specific support + * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will also + * `#include ` as well. */ #ifndef SDL_intrin_h_ @@ -28,6 +51,169 @@ #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LSX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LASX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports ARM NEON intrinsics. + * + * If this macro is defined, SDL will have already included `` + * ``, ``, and ``, as appropriate. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NEON_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports PowerPC Altivec intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALTIVEC_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel MMX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + */ +#define SDL_MMX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE3 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE3_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE4_1_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + */ +#define SDL_SSE4_2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX2_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics. + * + * AVX-512F is also sometimes referred to as "AVX-512 Foundation." + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX2_INTRINSICS + */ +#define SDL_AVX512F_INTRINSICS 1 +#endif + /* Need to do this here because intrin.h has C++ code in it */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) @@ -81,7 +267,21 @@ _m_prefetch(void *__P) #endif #endif /* compiler version */ -#if defined(__clang__) && defined(__has_attribute) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro to decide if the compiler supports `__attribute__((target))`. + * + * Even though this is defined in SDL's public headers, it is generally not + * used directly by apps. Apps should probably just use SDL_TARGETING + * directly, instead. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) # if __has_attribute(target) # define SDL_HAS_TARGET_ATTRIBS # endif @@ -91,7 +291,55 @@ _m_prefetch(void *__P) # define SDL_HAS_TARGET_ATTRIBS #endif -#ifdef SDL_HAS_TARGET_ATTRIBS + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a function as targeting a specific CPU architecture. + * + * This is a hint to the compiler that a function should be built with support + * for a CPU instruction set that might be different than the rest of the + * program. + * + * The particulars of this are explained in the GCC documentation: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute + * + * An example of using this feature is to turn on SSE2 support for a specific + * function, even if the rest of the source code is not compiled to use SSE2 + * code: + * + * ```c + * #ifdef SDL_SSE2_INTRINSICS + * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) { + * ...use SSE2 intrinsic functions, etc... + * } + * #endif + * + * // later... + * #ifdef SDL_SSE2_INTRINSICS + * if (SDL_HasSSE2()) { + * DoSomethingWithSSE2(str); + * } + * #endif + * ``` + * + * The application is, on a whole, built without SSE2 instructions, so it will + * run on Intel machines that don't support SSE2. But then at runtime, it + * checks if the system supports the instructions, and then calls into a + * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't + * used on platforms that don't have SSE2 at all. + * + * On compilers without target support, this is defined to nothing. + * + * This symbol is used by SDL internally, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TARGETING(x) __attribute__((target(x))) + +#elif defined(SDL_HAS_TARGET_ATTRIBS) # define SDL_TARGETING(x) __attribute__((target(x))) #else # define SDL_TARGETING(x) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_iostream.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_iostream.h index a306deb..4ca1609 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_iostream.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_iostream.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,7 @@ * # CategoryIOStream * * SDL provides an abstract interface for reading and writing data streams. It - * offers implementations for files, memory, etc, and the app can provideo + * offers implementations for files, memory, etc, and the app can provide * their own implementations, too. * * SDL_IOStream is not related to the standard C++ iostream class, other than @@ -48,7 +48,7 @@ extern "C" { /** * SDL_IOStream status, set by a read or write operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOStatus { @@ -66,13 +66,13 @@ typedef enum SDL_IOStatus * These map to the same "whence" concept that `fseek` or `lseek` use in the * standard C runtime. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOWhence { SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ - SDL_IO_SEEK_END, /**< Seek relative to the end of data */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ } SDL_IOWhence; /** @@ -83,10 +83,17 @@ typedef enum SDL_IOWhence * already offers several common types of I/O streams, via functions like * SDL_IOFromFile() and SDL_IOFromMem(). * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_IOStreamInterface { + /* The version of this interface */ + Uint32 version; + /** * Return the number of bytes in this SDL_IOStream * @@ -126,18 +133,41 @@ typedef struct SDL_IOStreamInterface */ size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + /** * Close and free any allocated resources. * - * The SDL_IOStream is still destroyed even if this fails, so clean up anything - * even if flushing to disk returns an error. + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. * - * \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data. + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); } SDL_IOStreamInterface; +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); /** * The read/write operation structure. @@ -147,7 +177,7 @@ typedef struct SDL_IOStreamInterface * SDL_OpenIO() to provide their own stream implementation behind this * struct's abstract interface. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_IOStream SDL_IOStream; @@ -217,6 +247,8 @@ typedef struct SDL_IOStream SDL_IOStream; * than your app, trying to use this pointer will almost certainly result in * a crash! This is mostly a problem on Windows; make sure you build SDL and * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access * the filesystem. If SDL used some other method to access the filesystem, @@ -228,9 +260,12 @@ typedef struct SDL_IOStream SDL_IOStream; * \returns a pointer to the SDL_IOStream structure that is created or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -240,6 +275,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" /** @@ -257,15 +293,25 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromConstMem * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -273,6 +319,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons */ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + /** * Use this function to prepare a read-only memory buffer for use with * SDL_IOStream. @@ -290,12 +339,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * If you need to write to a memory buffer, you should use SDL_IOFromMem() * with a writable buffer of memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromMem * \sa SDL_CloseIO @@ -323,7 +381,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO * \sa SDL_ReadIO @@ -347,20 +407,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * read/write a common data source, you should use the built-in * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. * - * You must free the returned pointer with SDL_CloseIO(). - * * This function makes a copy of `iface` and the caller does not need to keep - * this data around after this call. + * it around after this call. * - * \param iface the function pointers that implement this SDL_IOStream. - * \param userdata the app-controlled pointer that is passed to iface's - * functions when called. + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a pointer to the allocated memory on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE * \sa SDL_IOFromConstMem * \sa SDL_IOFromFile * \sa SDL_IOFromMem @@ -372,21 +433,32 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any * resources used by the stream and frees the SDL_IOStream itself. This - * returns SDL_TRUE on success, or SDL_FALSE if the stream failed to flush to - * its output (e.g. to disk). + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). * - * Note that if this fails to flush the stream to disk, this function reports - * an error, but the SDL_IOStream is still invalid once this function returns. + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. * * \param context SDL_IOStream structure to close. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenIO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); /** * Get the properties associated with an SDL_IOStream. @@ -395,7 +467,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); @@ -413,10 +487,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *c * \param context the SDL_IOStream to query. * \returns an SDL_IOStatus enum with the current state. * - * \threadsafety This function should not be called at the same time that - * another thread is operating on the same SDL_IOStream. + * \threadsafety This function is not thread safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); @@ -428,7 +501,9 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); * negative error code on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); @@ -450,10 +525,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * negative. * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, * `SDL_IO_SEEK_END`. - * \returns the final offset in the data stream after the seek or a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TellIO */ @@ -471,7 +548,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs * \returns the current offset in the stream, or -1 if the information can not * be determined. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SeekIO */ @@ -481,10 +560,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * Read from a data source. * * This function reads up `size` bytes from the data source to the area - * pointed at by `ptr`. This function may read less bytes than requested. It - * will return zero when the data stream is completely read, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR. + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. * * \param context a pointer to an SDL_IOStream structure. * \param ptr a pointer to a buffer to read data into. @@ -492,7 +573,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * \returns the number of bytes read, or 0 on end of file or other failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WriteIO * \sa SDL_GetIOStatus @@ -519,11 +602,14 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \returns the number of bytes written, which will be less than `size` on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_ReadIO * \sa SDL_SeekIO + * \sa SDL_FlushIO * \sa SDL_GetIOStatus */ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); @@ -540,7 +626,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOvprintf * \sa SDL_WriteIO @@ -558,13 +646,35 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_WriteIO */ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + /** * Load all the data from an SDL data stream. * @@ -575,17 +685,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * The data should be freed with SDL_free(). * * \param src the SDL_IOStream to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio); +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); /** * Load all the data from a file path. @@ -601,12 +715,55 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile */ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); +/** + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); + +/** + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); + /** * \name Read endian functions * @@ -617,26 +774,63 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi /** * Use this function to read a byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure or EOF; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); /** * Use this function to read a signed byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of little-endian data from an @@ -645,30 +839,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value) * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data. - * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); - -/** - * Use this function to read 16 bits of little-endian data from an - * SDL_IOStream and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -677,14 +862,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -693,14 +885,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -709,14 +908,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -725,14 +931,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -741,14 +954,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -757,14 +977,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -773,14 +1000,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -789,14 +1023,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -805,14 +1046,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -821,14 +1069,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); /* @} *//* Read endian functions */ /** @@ -843,24 +1098,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); /** * Use this function to write a signed byte to an SDL_IOStream. * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -872,12 +1131,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value) * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -889,12 +1150,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -905,12 +1168,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -921,12 +1186,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -938,12 +1205,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -955,12 +1224,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -971,12 +1242,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -987,12 +1260,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1004,12 +1279,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1021,12 +1298,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1037,12 +1316,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1053,12 +1334,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); /* @} *//* Write endian functions */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_joystick.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_joystick.h index 43bc1e9..d15668b 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_joystick.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_joystick.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,8 +25,8 @@ * SDL joystick support. * * This is the lower-level joystick handling. If you want the simpler option, - * where what buttons does what is well-defined, you should use the gamepad - * API instead. + * where what each button does is well-defined, you should use the gamepad API + * instead. * * The term "instance_id" is the current instantiation of a joystick device in * the system, if the joystick is removed and then re-inserted then it will @@ -81,7 +81,7 @@ extern SDL_Mutex *SDL_joystick_lock; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Joystick SDL_Joystick; @@ -93,7 +93,7 @@ typedef struct SDL_Joystick SDL_Joystick; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_JoystickID; @@ -107,7 +107,7 @@ typedef Uint32 SDL_JoystickID; * This is by no means a complete list of everything that can be plugged into * a computer. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickType { @@ -120,7 +120,8 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_GUITAR, SDL_JOYSTICK_TYPE_DRUM_KIT, SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT } SDL_JoystickType; /** @@ -129,7 +130,7 @@ typedef enum SDL_JoystickType * This is used by SDL_GetJoystickConnectionState to report how a device is * connected to the system. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickConnectionState { @@ -142,7 +143,7 @@ typedef enum SDL_JoystickConnectionState /** * The largest value an SDL_Joystick's axis can report. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MIN */ @@ -153,19 +154,13 @@ typedef enum SDL_JoystickConnectionState * * This is a negative number! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MAX */ #define SDL_JOYSTICK_AXIS_MIN -32768 -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - /* Function prototypes */ /** @@ -175,27 +170,27 @@ typedef enum SDL_JoystickConnectionState * joysticks while processing to guarantee that the joystick list won't change * and joystick and gamepad events will not be delivered. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); /** * Unlocking for atomic access to the joystick API. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); /** * Return whether a joystick is currently connected. * - * \returns SDL_TRUE if a joystick is connected, SDL_FALSE otherwise. + * \returns true if a joystick is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. @@ -206,7 +201,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasJoystick * \sa SDL_OpenJoystick @@ -222,7 +217,7 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickName * \sa SDL_GetJoysticks @@ -238,7 +233,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPath * \sa SDL_GetJoysticks @@ -253,7 +248,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a joystick, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoysticks @@ -269,7 +264,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID i * \returns the GUID of the selected joystick. If called with an invalid * instance_id, this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUID * \sa SDL_GUIDToString @@ -286,7 +281,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID ins * \returns the USB vendor ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendor * \sa SDL_GetJoysticks @@ -303,7 +298,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID ins * \returns the USB product ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProduct * \sa SDL_GetJoysticks @@ -320,7 +315,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID in * \returns the product version of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersion * \sa SDL_GetJoysticks @@ -337,7 +332,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_Joysti * invalid instance_id, this function returns * `SDL_JOYSTICK_TYPE_UNKNOWN`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickType * \sa SDL_GetJoysticks @@ -354,7 +349,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti * \returns a joystick identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseJoystick */ @@ -367,7 +362,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID insta * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); @@ -378,7 +373,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_SetJoystickPlayerIndex @@ -388,7 +383,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int pl /** * The structure that describes a virtual joystick touchpad. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -401,7 +396,7 @@ typedef struct SDL_VirtualJoystickTouchpadDesc /** * The structure that describes a virtual joystick sensor. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -414,16 +409,19 @@ typedef struct SDL_VirtualJoystickSensorDesc /** * The structure that describes a virtual joystick. * - * All elements of this structure are optional and can be left 0. + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE * \sa SDL_VirtualJoystickSensorDesc * \sa SDL_VirtualJoystickTouchpadDesc */ typedef struct SDL_VirtualJoystickDesc { + Uint32 version; /**< the version of this interface */ Uint16 type; /**< `SDL_JoystickType` */ Uint16 padding; /**< unused */ Uint16 vendor_id; /**< the USB vendor ID of this joystick */ @@ -446,22 +444,32 @@ typedef struct SDL_VirtualJoystickDesc void *userdata; /**< User data pointer passed to callbacks */ void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - SDL_bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - SDL_bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - SDL_bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - SDL_bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - SDL_bool (SDLCALL *SetSensorsEnabled)(void *userdata, SDL_bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ } SDL_VirtualJoystickDesc; +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + /** * Attach a new virtual joystick. * - * \param desc joystick description. + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DetachVirtualJoystick */ @@ -472,24 +480,24 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V * * \param instance_id the joystick instance ID, previously returned from * SDL_AttachVirtualJoystick(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); /** * Query whether or not a joystick is virtual. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * \returns true if the joystick is virtual, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); /** * Set the state of an axis on an opened virtual joystick. @@ -507,12 +515,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instan * \param joystick the virtual joystick on which to set state. * \param axis the index of the axis on the virtual joystick to update. * \param value the new value for the specified axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); /** * Generate ball motion on an opened virtual joystick. @@ -527,12 +535,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *jo * \param ball the index of the ball on the virtual joystick to update. * \param xrel the relative motion on the X axis. * \param yrel the relative motion on the Y axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); /** * Set the state of a button on an opened virtual joystick. @@ -545,13 +553,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *jo * * \param joystick the virtual joystick on which to set state. * \param button the index of the button on the virtual joystick to update. - * \param value the new value for the specified button. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); /** * Set the state of a hat on an opened virtual joystick. @@ -565,12 +573,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick * * \param joystick the virtual joystick on which to set state. * \param hat the index of the hat on the virtual joystick to update. * \param value the new value for the specified hat. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); /** * Set touchpad finger state on an opened virtual joystick. @@ -585,19 +593,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joy * \param touchpad the index of the touchpad on the virtual joystick to * update. * \param finger the index of the finger on the touchpad to set. - * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the - * finger is released. + * \param down true if the finger is pressed, false if the finger is released. * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param pressure the pressure of the finger. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); /** * Send a sensor update for an opened virtual joystick. @@ -614,12 +621,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick * the sensor reading. * \param data the data associated with the sensor reading. * \param num_values the number of values pointed to by `data`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); /** * Get the properties associated with a joystick. @@ -641,7 +648,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joyst * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); @@ -658,7 +665,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickNameForID */ @@ -671,7 +678,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPathForID */ @@ -686,7 +693,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joyst * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the player index, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickPlayerIndex */ @@ -698,14 +705,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param player_index player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); /** * Get the implementation-dependent GUID for the joystick. @@ -717,7 +724,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *jo * this function returns a zero GUID; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GUIDToString @@ -732,7 +739,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendorForID */ @@ -746,7 +753,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductForID */ @@ -760,7 +767,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the product version of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersionForID */ @@ -775,7 +782,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j * \returns the firmware version of the selected joystick, or 0 if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); @@ -788,7 +795,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick * * \returns the serial number of the selected joystick, or NULL if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); @@ -798,7 +805,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the SDL_JoystickType of the selected joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickTypeForID */ @@ -817,7 +824,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j * \param crc16 a pointer filled in with a CRC used to distinguish different * products with the same VID/PID, or 0 if not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID */ @@ -827,12 +834,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 * * Get the status of a specified joystick. * * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); /** * Get the instance ID of an opened joystick. @@ -841,7 +848,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic * \returns the instance ID of the specified joystick on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); @@ -856,7 +863,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst * \returns the number of axis controls/number of axes on success or -1 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickAxis * \sa SDL_GetNumJoystickBalls @@ -877,7 +884,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); * \returns the number of trackballs on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickBall * \sa SDL_GetNumJoystickAxes @@ -893,7 +900,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); * \returns the number of POV hats on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickHat * \sa SDL_GetNumJoystickAxes @@ -909,7 +916,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); * \returns the number of buttons on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickButton * \sa SDL_GetNumJoystickAxes @@ -927,12 +934,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick * * \param enabled whether to process joystick events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_JoystickEventsEnabled * \sa SDL_UpdateJoysticks */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); /** * Query the state of joystick event processing. @@ -941,14 +948,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); * yourself and check the state of the joystick when you want joystick * information. * - * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE - * otherwise. + * \returns true if joystick events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); /** * Update the current state of the open joysticks. @@ -956,7 +962,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); * This is called automatically by the event loop if any joystick events are * enabled. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); @@ -978,7 +984,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); * \returns a 16-bit signed integer representing the current position of the * axis or 0 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickAxes */ @@ -994,11 +1000,11 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i * \param joystick an SDL_Joystick structure containing joystick information. * \param axis the axis to query; the axis indices start at index 0. * \param state upon return, the initial value is supplied here. - * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \returns true if this axis has any initial value, or false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); /** * Get the ball axis change since the last poll. @@ -1012,14 +1018,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic * \param ball the ball index to query; ball indices start at index 0. * \param dx stores the difference in the x axis position since the last poll. * \param dy stores the difference in the y axis position since the last poll. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickBalls */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); /** * Get the current state of a POV hat on a joystick. @@ -1030,7 +1036,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickHats */ @@ -1052,13 +1058,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickButtons */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); /** * Start a rumble effect. @@ -1075,11 +1081,11 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE, or SDL_FALSE if rumble isn't supported on this joystick. + * \returns true, or false if rumble isn't supported on this joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the joystick's triggers. @@ -1101,14 +1107,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a joystick's LED color. @@ -1123,12 +1129,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *jo * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** * Send a joystick specific effect packet. @@ -1136,19 +1142,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, * \param joystick the joystick to affect. * \param data the data to send to the joystick. * \param size the size of the data to send to the joystick. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); /** * Close a joystick previously opened with SDL_OpenJoystick(). * * \param joystick the joystick device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenJoystick */ @@ -1162,7 +1168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); @@ -1183,7 +1189,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keyboard.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keyboard.h index ec6c3f2..afa77b6 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keyboard.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keyboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeyboard * * SDL keyboard management. + * + * Please refer to the Best Keyboard Practices document for details on how + * best to accept keyboard input in various types of programs: + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keyboard_h_ @@ -31,6 +36,9 @@ #include #include #include +#include +#include +#include #include #include @@ -47,7 +55,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_KeyboardID; @@ -56,13 +64,15 @@ typedef Uint32 SDL_KeyboardID; /** * Return whether a keyboard is currently connected. * - * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise. + * \returns true if a keyboard is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); /** * Get a list of currently connected keyboards. @@ -78,7 +88,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardNameForID * \sa SDL_HasKeyboard @@ -94,7 +106,9 @@ extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); * \returns the name of the selected keyboard or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ @@ -105,7 +119,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID * * \returns the window with keyboard focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); @@ -116,9 +132,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * valid for the whole lifetime of the application and should not be freed by * the caller. * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. + * A array element with a value of true means that the key is pressed and a + * value of false means that it is not. Indexes into this array are obtained + * by using SDL_Scancode values. * * Use SDL_PumpEvents() to update the state array. * @@ -133,19 +149,23 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PumpEvents * \sa SDL_ResetKeyboard */ -extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys); +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); /** * Clear the state of the keyboard. * * This function will generate key up events for all pressed keys. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState */ @@ -157,7 +177,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); * \returns an OR'd combination of the modifier keys for the keyboard. See * SDL_Keymod for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState * \sa SDL_SetModState @@ -177,7 +199,9 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * * \param modstate the desired SDL_Keymod for the keyboard. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetModState */ @@ -189,21 +213,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * If you want to get the keycode as it would be delivered in key events, * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should - * pass `key_event` as SDL_TRUE. Otherwise this function simply translates the + * pass `key_event` as true. Otherwise this function simply translates the * scancode based on the given modifier state. * * \param scancode the desired SDL_Scancode to query. * \param modstate the modifier state to use when translating the scancode to * a keycode. - * \param key_event SDL_TRUE if the keycode will be used in key events. + * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyName * \sa SDL_GetScancodeFromKey */ -extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, SDL_bool key_event); +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); /** * Get the scancode corresponding to the given key code according to the @@ -217,7 +243,9 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan * scancode generates this key, may be NULL. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetScancodeName @@ -231,14 +259,16 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \param name the name to use for the scancode, encoded as UTF-8. The string * is not copied, so the pointer given to this function must stay * valid while SDL is being used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeName */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); /** * Get a human-readable name for a scancode. @@ -256,7 +286,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, * \returns a pointer to the name for the scancode. If the scancode doesn't * have a name this function returns an empty string (""). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeFromKey * \sa SDL_GetScancodeFromName @@ -271,7 +303,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scanco * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't * recognized; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetScancodeFromKey @@ -284,10 +318,14 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * * If the key doesn't have a name, this function returns an empty string (""). * + * Letters will be presented in their uppercase form, if applicable. + * * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetKeyFromScancode @@ -302,7 +340,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetKeyName @@ -319,20 +359,24 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * \param window the window to enable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInputWithProperties * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); /** * Text input type. @@ -341,7 +385,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); * value is valid on every platform, but where a value isn't supported, a * reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -361,12 +405,11 @@ typedef enum SDL_TextInputType /** * Auto capitalization type. * - * These are the valid values for - * SDL_PROP_TEXTINPUT_AUTOCAPITALIZATION_NUMBER. Not every value is valid on - * every platform, but where a value isn't supported, a reasonable fallback - * will be used. + * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. + * Not every value is valid on every platform, but where a value isn't + * supported, a reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -388,7 +431,9 @@ typedef enum SDL_Capitalization * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * These are the supported properties: * @@ -400,11 +445,11 @@ typedef enum SDL_Capitalization * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail * addresses, usernames, and passwords. * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion - * and auto correction, defaults to SDL_TRUE. + * and auto correction, defaults to true. * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text - * are allowed. This defaults to SDL_TRUE if SDL_HINT_RETURN_KEY_HIDES_IME - * is "0" or is not set, and defaults to SDL_FALSE if - * SDL_HINT_RETURN_KEY_HIDES_IME is "1". + * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is + * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME + * is "1". * * On Android you can directly specify the input type: * @@ -414,17 +459,19 @@ typedef enum SDL_Capitalization * * \param window the window to enable text input. * \param props the properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInput * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" @@ -436,13 +483,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window * Check whether or not Unicode text input events are enabled for a window. * * \param window the window to check. - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * \returns true if text input events are enabled else false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); /** * Stop receiving any text input events in a window. @@ -451,28 +500,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); * it. * * \param window the window to disable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); /** * Dismiss the composition window/IME without disabling the subsystem. * * \param window the window to affect. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); /** * Set the area used to type Unicode text input. @@ -485,15 +538,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); * coordinates, or NULL to clear it. * \param cursor the offset of the current cursor location relative to * `rect->x`, in window coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextInputArea * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); /** * Get the area used to type Unicode text input. @@ -505,39 +560,45 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, co * may be NULL. * \param cursor a pointer to the offset of the current cursor location * relative to `rect->x`, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); /** * Check whether the platform has screen keyboard support. * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. + * \returns true if the platform has some screen keyboard support or false if + * not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_ScreenKeyboardShown */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * Check whether the screen keyboard is shown for given window. * * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * \returns true if screen keyboard is shown or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasScreenKeyboardSupport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keycode.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keycode.h index 2d03a3d..61b68e7 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keycode.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_keycode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeycode * * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keycode_h_ @@ -42,272 +47,284 @@ * A special exception is the number keys at the top of the keyboard which map * to SDLK_0...SDLK_9 on AZERTY layouts. * - * \since This datatype is available since SDL 3.0.0. + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_Keycode; -#define SDLK_SCANCODE_MASK (1u<<30) +#define SDLK_EXTENDED_MASK (1u << 29) +#define SDLK_SCANCODE_MASK (1u << 30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -#define SDLK_UNKNOWN 0x00000000u /* 0 */ -#define SDLK_RETURN 0x0000000du /* '\r' */ -#define SDLK_ESCAPE 0x0000001bu /* '\x1B' */ -#define SDLK_BACKSPACE 0x00000008u /* '\b' */ -#define SDLK_TAB 0x00000009u /* '\t' */ -#define SDLK_SPACE 0x00000020u /* ' ' */ -#define SDLK_EXCLAIM 0x00000021u /* '!' */ -#define SDLK_DBLAPOSTROPHE 0x00000022u /* '"' */ -#define SDLK_HASH 0x00000023u /* '#' */ -#define SDLK_DOLLAR 0x00000024u /* '$' */ -#define SDLK_PERCENT 0x00000025u /* '%' */ -#define SDLK_AMPERSAND 0x00000026u /* '&' */ -#define SDLK_APOSTROPHE 0x00000027u /* '\'' */ -#define SDLK_LEFTPAREN 0x00000028u /* '(' */ -#define SDLK_RIGHTPAREN 0x00000029u /* ')' */ -#define SDLK_ASTERISK 0x0000002au /* '*' */ -#define SDLK_PLUS 0x0000002bu /* '+' */ -#define SDLK_COMMA 0x0000002cu /* ',' */ -#define SDLK_MINUS 0x0000002du /* '-' */ -#define SDLK_PERIOD 0x0000002eu /* '.' */ -#define SDLK_SLASH 0x0000002fu /* '/' */ -#define SDLK_0 0x00000030u /* '0' */ -#define SDLK_1 0x00000031u /* '1' */ -#define SDLK_2 0x00000032u /* '2' */ -#define SDLK_3 0x00000033u /* '3' */ -#define SDLK_4 0x00000034u /* '4' */ -#define SDLK_5 0x00000035u /* '5' */ -#define SDLK_6 0x00000036u /* '6' */ -#define SDLK_7 0x00000037u /* '7' */ -#define SDLK_8 0x00000038u /* '8' */ -#define SDLK_9 0x00000039u /* '9' */ -#define SDLK_COLON 0x0000003au /* ':' */ -#define SDLK_SEMICOLON 0x0000003bu /* ';' */ -#define SDLK_LESS 0x0000003cu /* '<' */ -#define SDLK_EQUALS 0x0000003du /* '=' */ -#define SDLK_GREATER 0x0000003eu /* '>' */ -#define SDLK_QUESTION 0x0000003fu /* '?' */ -#define SDLK_AT 0x00000040u /* '@' */ -#define SDLK_LEFTBRACKET 0x0000005bu /* '[' */ -#define SDLK_BACKSLASH 0x0000005cu /* '\\' */ -#define SDLK_RIGHTBRACKET 0x0000005du /* ']' */ -#define SDLK_CARET 0x0000005eu /* '^' */ -#define SDLK_UNDERSCORE 0x0000005fu /* '_' */ -#define SDLK_GRAVE 0x00000060u /* '`' */ -#define SDLK_A 0x00000061u /* 'a' */ -#define SDLK_B 0x00000062u /* 'b' */ -#define SDLK_C 0x00000063u /* 'c' */ -#define SDLK_D 0x00000064u /* 'd' */ -#define SDLK_E 0x00000065u /* 'e' */ -#define SDLK_F 0x00000066u /* 'f' */ -#define SDLK_G 0x00000067u /* 'g' */ -#define SDLK_H 0x00000068u /* 'h' */ -#define SDLK_I 0x00000069u /* 'i' */ -#define SDLK_J 0x0000006au /* 'j' */ -#define SDLK_K 0x0000006bu /* 'k' */ -#define SDLK_L 0x0000006cu /* 'l' */ -#define SDLK_M 0x0000006du /* 'm' */ -#define SDLK_N 0x0000006eu /* 'n' */ -#define SDLK_O 0x0000006fu /* 'o' */ -#define SDLK_P 0x00000070u /* 'p' */ -#define SDLK_Q 0x00000071u /* 'q' */ -#define SDLK_R 0x00000072u /* 'r' */ -#define SDLK_S 0x00000073u /* 's' */ -#define SDLK_T 0x00000074u /* 't' */ -#define SDLK_U 0x00000075u /* 'u' */ -#define SDLK_V 0x00000076u /* 'v' */ -#define SDLK_W 0x00000077u /* 'w' */ -#define SDLK_X 0x00000078u /* 'x' */ -#define SDLK_Y 0x00000079u /* 'y' */ -#define SDLK_Z 0x0000007au /* 'z' */ -#define SDLK_LEFTBRACE 0x0000007bu /* '{' */ -#define SDLK_PIPE 0x0000007cu /* '|' */ -#define SDLK_RIGHTBRACE 0x0000007du /* '}' */ -#define SDLK_TILDE 0x0000007eu /* '~' */ -#define SDLK_DELETE 0x0000007fu /* '\x7F' */ -#define SDLK_PLUSMINUS 0x000000b1u /* '±' */ -#define SDLK_CAPSLOCK 0x40000039u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ -#define SDLK_F1 0x4000003au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ -#define SDLK_F2 0x4000003bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ -#define SDLK_F3 0x4000003cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ -#define SDLK_F4 0x4000003du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ -#define SDLK_F5 0x4000003eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ -#define SDLK_F6 0x4000003fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ -#define SDLK_F7 0x40000040u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ -#define SDLK_F8 0x40000041u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ -#define SDLK_F9 0x40000042u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ -#define SDLK_F10 0x40000043u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ -#define SDLK_F11 0x40000044u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ -#define SDLK_F12 0x40000045u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ -#define SDLK_PRINTSCREEN 0x40000046u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ -#define SDLK_SCROLLLOCK 0x40000047u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ -#define SDLK_PAUSE 0x40000048u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ -#define SDLK_INSERT 0x40000049u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ -#define SDLK_HOME 0x4000004au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ -#define SDLK_PAGEUP 0x4000004bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ -#define SDLK_END 0x4000004du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ -#define SDLK_PAGEDOWN 0x4000004eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ -#define SDLK_RIGHT 0x4000004fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ -#define SDLK_LEFT 0x40000050u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ -#define SDLK_DOWN 0x40000051u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ -#define SDLK_UP 0x40000052u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ -#define SDLK_NUMLOCKCLEAR 0x40000053u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ -#define SDLK_KP_DIVIDE 0x40000054u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ -#define SDLK_KP_MULTIPLY 0x40000055u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ -#define SDLK_KP_MINUS 0x40000056u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ -#define SDLK_KP_PLUS 0x40000057u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ -#define SDLK_KP_ENTER 0x40000058u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ -#define SDLK_KP_1 0x40000059u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ -#define SDLK_KP_2 0x4000005au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ -#define SDLK_KP_3 0x4000005bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ -#define SDLK_KP_4 0x4000005cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ -#define SDLK_KP_5 0x4000005du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ -#define SDLK_KP_6 0x4000005eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ -#define SDLK_KP_7 0x4000005fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ -#define SDLK_KP_8 0x40000060u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ -#define SDLK_KP_9 0x40000061u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ -#define SDLK_KP_0 0x40000062u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ -#define SDLK_KP_PERIOD 0x40000063u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ -#define SDLK_APPLICATION 0x40000065u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ -#define SDLK_POWER 0x40000066u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ -#define SDLK_KP_EQUALS 0x40000067u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ -#define SDLK_F13 0x40000068u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ -#define SDLK_F14 0x40000069u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ -#define SDLK_F15 0x4000006au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ -#define SDLK_F16 0x4000006bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ -#define SDLK_F17 0x4000006cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ -#define SDLK_F18 0x4000006du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ -#define SDLK_F19 0x4000006eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ -#define SDLK_F20 0x4000006fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ -#define SDLK_F21 0x40000070u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ -#define SDLK_F22 0x40000071u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ -#define SDLK_F23 0x40000072u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ -#define SDLK_F24 0x40000073u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ -#define SDLK_EXECUTE 0x40000074u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ -#define SDLK_HELP 0x40000075u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ -#define SDLK_MENU 0x40000076u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ -#define SDLK_SELECT 0x40000077u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ -#define SDLK_STOP 0x40000078u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ -#define SDLK_AGAIN 0x40000079u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ -#define SDLK_UNDO 0x4000007au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ -#define SDLK_CUT 0x4000007bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ -#define SDLK_COPY 0x4000007cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ -#define SDLK_PASTE 0x4000007du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ -#define SDLK_FIND 0x4000007eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ -#define SDLK_MUTE 0x4000007fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ -#define SDLK_VOLUMEUP 0x40000080u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ -#define SDLK_VOLUMEDOWN 0x40000081u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ -#define SDLK_KP_COMMA 0x40000085u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ -#define SDLK_KP_EQUALSAS400 0x40000086u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ -#define SDLK_ALTERASE 0x40000099u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ -#define SDLK_SYSREQ 0x4000009au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ -#define SDLK_CANCEL 0x4000009bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ -#define SDLK_CLEAR 0x4000009cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ -#define SDLK_PRIOR 0x4000009du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ -#define SDLK_RETURN2 0x4000009eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ -#define SDLK_SEPARATOR 0x4000009fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ -#define SDLK_OUT 0x400000a0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ -#define SDLK_OPER 0x400000a1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ -#define SDLK_CLEARAGAIN 0x400000a2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ -#define SDLK_CRSEL 0x400000a3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ -#define SDLK_EXSEL 0x400000a4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ -#define SDLK_KP_00 0x400000b0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ -#define SDLK_KP_000 0x400000b1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ -#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ -#define SDLK_DECIMALSEPARATOR 0x400000b3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ -#define SDLK_CURRENCYUNIT 0x400000b4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ -#define SDLK_CURRENCYSUBUNIT 0x400000b5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ -#define SDLK_KP_LEFTPAREN 0x400000b6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ -#define SDLK_KP_RIGHTPAREN 0x400000b7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ -#define SDLK_KP_LEFTBRACE 0x400000b8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ -#define SDLK_KP_RIGHTBRACE 0x400000b9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ -#define SDLK_KP_TAB 0x400000bau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ -#define SDLK_KP_BACKSPACE 0x400000bbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ -#define SDLK_KP_A 0x400000bcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ -#define SDLK_KP_B 0x400000bdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ -#define SDLK_KP_C 0x400000beu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ -#define SDLK_KP_D 0x400000bfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ -#define SDLK_KP_E 0x400000c0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ -#define SDLK_KP_F 0x400000c1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ -#define SDLK_KP_XOR 0x400000c2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ -#define SDLK_KP_POWER 0x400000c3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ -#define SDLK_KP_PERCENT 0x400000c4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ -#define SDLK_KP_LESS 0x400000c5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ -#define SDLK_KP_GREATER 0x400000c6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ -#define SDLK_KP_AMPERSAND 0x400000c7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ -#define SDLK_KP_DBLAMPERSAND 0x400000c8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ -#define SDLK_KP_VERTICALBAR 0x400000c9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ -#define SDLK_KP_DBLVERTICALBAR 0x400000cau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ -#define SDLK_KP_COLON 0x400000cbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ -#define SDLK_KP_HASH 0x400000ccu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ -#define SDLK_KP_SPACE 0x400000cdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ -#define SDLK_KP_AT 0x400000ceu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ -#define SDLK_KP_EXCLAM 0x400000cfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ -#define SDLK_KP_MEMSTORE 0x400000d0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ -#define SDLK_KP_MEMRECALL 0x400000d1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ -#define SDLK_KP_MEMCLEAR 0x400000d2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ -#define SDLK_KP_MEMADD 0x400000d3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ -#define SDLK_KP_MEMSUBTRACT 0x400000d4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ -#define SDLK_KP_MEMMULTIPLY 0x400000d5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ -#define SDLK_KP_MEMDIVIDE 0x400000d6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ -#define SDLK_KP_PLUSMINUS 0x400000d7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ -#define SDLK_KP_CLEAR 0x400000d8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ -#define SDLK_KP_CLEARENTRY 0x400000d9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ -#define SDLK_KP_BINARY 0x400000dau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ -#define SDLK_KP_OCTAL 0x400000dbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ -#define SDLK_KP_DECIMAL 0x400000dcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ -#define SDLK_KP_HEXADECIMAL 0x400000ddu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ -#define SDLK_LCTRL 0x400000e0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ -#define SDLK_LSHIFT 0x400000e1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ -#define SDLK_LALT 0x400000e2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ -#define SDLK_LGUI 0x400000e3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ -#define SDLK_RCTRL 0x400000e4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ -#define SDLK_RSHIFT 0x400000e5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ -#define SDLK_RALT 0x400000e6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ -#define SDLK_RGUI 0x400000e7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ -#define SDLK_MODE 0x40000101u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ -#define SDLK_SLEEP 0x40000102u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ -#define SDLK_WAKE 0x40000103u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ -#define SDLK_CHANNEL_INCREMENT 0x40000104u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ -#define SDLK_CHANNEL_DECREMENT 0x40000105u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ -#define SDLK_MEDIA_PLAY 0x40000106u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ -#define SDLK_MEDIA_PAUSE 0x40000107u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ -#define SDLK_MEDIA_RECORD 0x40000108u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ -#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ -#define SDLK_MEDIA_REWIND 0x4000010au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ -#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ -#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ -#define SDLK_MEDIA_STOP 0x4000010du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ -#define SDLK_MEDIA_EJECT 0x4000010eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ -#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ -#define SDLK_MEDIA_SELECT 0x40000110u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ -#define SDLK_AC_NEW 0x40000111u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ -#define SDLK_AC_OPEN 0x40000112u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ -#define SDLK_AC_CLOSE 0x40000113u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ -#define SDLK_AC_EXIT 0x40000114u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ -#define SDLK_AC_SAVE 0x40000115u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ -#define SDLK_AC_PRINT 0x40000116u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ -#define SDLK_AC_PROPERTIES 0x40000117u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ -#define SDLK_AC_SEARCH 0x40000118u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ -#define SDLK_AC_HOME 0x40000119u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ -#define SDLK_AC_BACK 0x4000011au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ -#define SDLK_AC_FORWARD 0x4000011bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ -#define SDLK_AC_STOP 0x4000011cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ -#define SDLK_AC_REFRESH 0x4000011du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ -#define SDLK_AC_BOOKMARKS 0x4000011eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ -#define SDLK_SOFTLEFT 0x4000011fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ -#define SDLK_SOFTRIGHT 0x40000120u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ -#define SDLK_CALL 0x40000121u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ -#define SDLK_ENDCALL 0x40000122u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_UNKNOWN 0x00000000u /**< 0 */ +#define SDLK_RETURN 0x0000000du /**< '\r' */ +#define SDLK_ESCAPE 0x0000001bu /**< '\x1B' */ +#define SDLK_BACKSPACE 0x00000008u /**< '\b' */ +#define SDLK_TAB 0x00000009u /**< '\t' */ +#define SDLK_SPACE 0x00000020u /**< ' ' */ +#define SDLK_EXCLAIM 0x00000021u /**< '!' */ +#define SDLK_DBLAPOSTROPHE 0x00000022u /**< '"' */ +#define SDLK_HASH 0x00000023u /**< '#' */ +#define SDLK_DOLLAR 0x00000024u /**< '$' */ +#define SDLK_PERCENT 0x00000025u /**< '%' */ +#define SDLK_AMPERSAND 0x00000026u /**< '&' */ +#define SDLK_APOSTROPHE 0x00000027u /**< '\'' */ +#define SDLK_LEFTPAREN 0x00000028u /**< '(' */ +#define SDLK_RIGHTPAREN 0x00000029u /**< ')' */ +#define SDLK_ASTERISK 0x0000002au /**< '*' */ +#define SDLK_PLUS 0x0000002bu /**< '+' */ +#define SDLK_COMMA 0x0000002cu /**< ',' */ +#define SDLK_MINUS 0x0000002du /**< '-' */ +#define SDLK_PERIOD 0x0000002eu /**< '.' */ +#define SDLK_SLASH 0x0000002fu /**< '/' */ +#define SDLK_0 0x00000030u /**< '0' */ +#define SDLK_1 0x00000031u /**< '1' */ +#define SDLK_2 0x00000032u /**< '2' */ +#define SDLK_3 0x00000033u /**< '3' */ +#define SDLK_4 0x00000034u /**< '4' */ +#define SDLK_5 0x00000035u /**< '5' */ +#define SDLK_6 0x00000036u /**< '6' */ +#define SDLK_7 0x00000037u /**< '7' */ +#define SDLK_8 0x00000038u /**< '8' */ +#define SDLK_9 0x00000039u /**< '9' */ +#define SDLK_COLON 0x0000003au /**< ':' */ +#define SDLK_SEMICOLON 0x0000003bu /**< ';' */ +#define SDLK_LESS 0x0000003cu /**< '<' */ +#define SDLK_EQUALS 0x0000003du /**< '=' */ +#define SDLK_GREATER 0x0000003eu /**< '>' */ +#define SDLK_QUESTION 0x0000003fu /**< '?' */ +#define SDLK_AT 0x00000040u /**< '@' */ +#define SDLK_LEFTBRACKET 0x0000005bu /**< '[' */ +#define SDLK_BACKSLASH 0x0000005cu /**< '\\' */ +#define SDLK_RIGHTBRACKET 0x0000005du /**< ']' */ +#define SDLK_CARET 0x0000005eu /**< '^' */ +#define SDLK_UNDERSCORE 0x0000005fu /**< '_' */ +#define SDLK_GRAVE 0x00000060u /**< '`' */ +#define SDLK_A 0x00000061u /**< 'a' */ +#define SDLK_B 0x00000062u /**< 'b' */ +#define SDLK_C 0x00000063u /**< 'c' */ +#define SDLK_D 0x00000064u /**< 'd' */ +#define SDLK_E 0x00000065u /**< 'e' */ +#define SDLK_F 0x00000066u /**< 'f' */ +#define SDLK_G 0x00000067u /**< 'g' */ +#define SDLK_H 0x00000068u /**< 'h' */ +#define SDLK_I 0x00000069u /**< 'i' */ +#define SDLK_J 0x0000006au /**< 'j' */ +#define SDLK_K 0x0000006bu /**< 'k' */ +#define SDLK_L 0x0000006cu /**< 'l' */ +#define SDLK_M 0x0000006du /**< 'm' */ +#define SDLK_N 0x0000006eu /**< 'n' */ +#define SDLK_O 0x0000006fu /**< 'o' */ +#define SDLK_P 0x00000070u /**< 'p' */ +#define SDLK_Q 0x00000071u /**< 'q' */ +#define SDLK_R 0x00000072u /**< 'r' */ +#define SDLK_S 0x00000073u /**< 's' */ +#define SDLK_T 0x00000074u /**< 't' */ +#define SDLK_U 0x00000075u /**< 'u' */ +#define SDLK_V 0x00000076u /**< 'v' */ +#define SDLK_W 0x00000077u /**< 'w' */ +#define SDLK_X 0x00000078u /**< 'x' */ +#define SDLK_Y 0x00000079u /**< 'y' */ +#define SDLK_Z 0x0000007au /**< 'z' */ +#define SDLK_LEFTBRACE 0x0000007bu /**< '{' */ +#define SDLK_PIPE 0x0000007cu /**< '|' */ +#define SDLK_RIGHTBRACE 0x0000007du /**< '}' */ +#define SDLK_TILDE 0x0000007eu /**< '~' */ +#define SDLK_DELETE 0x0000007fu /**< '\x7F' */ +#define SDLK_PLUSMINUS 0x000000b1u /**< '\xB1' */ +#define SDLK_CAPSLOCK 0x40000039u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ +#define SDLK_F1 0x4000003au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ +#define SDLK_F2 0x4000003bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ +#define SDLK_F3 0x4000003cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ +#define SDLK_F4 0x4000003du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ +#define SDLK_F5 0x4000003eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ +#define SDLK_F6 0x4000003fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ +#define SDLK_F7 0x40000040u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ +#define SDLK_F8 0x40000041u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ +#define SDLK_F9 0x40000042u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ +#define SDLK_F10 0x40000043u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ +#define SDLK_F11 0x40000044u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ +#define SDLK_F12 0x40000045u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ +#define SDLK_PRINTSCREEN 0x40000046u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ +#define SDLK_SCROLLLOCK 0x40000047u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ +#define SDLK_PAUSE 0x40000048u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ +#define SDLK_INSERT 0x40000049u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ +#define SDLK_HOME 0x4000004au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ +#define SDLK_PAGEUP 0x4000004bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ +#define SDLK_END 0x4000004du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ +#define SDLK_PAGEDOWN 0x4000004eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ +#define SDLK_RIGHT 0x4000004fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ +#define SDLK_LEFT 0x40000050u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ +#define SDLK_DOWN 0x40000051u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ +#define SDLK_UP 0x40000052u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ +#define SDLK_NUMLOCKCLEAR 0x40000053u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ +#define SDLK_KP_DIVIDE 0x40000054u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ +#define SDLK_KP_MULTIPLY 0x40000055u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ +#define SDLK_KP_MINUS 0x40000056u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ +#define SDLK_KP_PLUS 0x40000057u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ +#define SDLK_KP_ENTER 0x40000058u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ +#define SDLK_KP_1 0x40000059u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ +#define SDLK_KP_2 0x4000005au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ +#define SDLK_KP_3 0x4000005bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ +#define SDLK_KP_4 0x4000005cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ +#define SDLK_KP_5 0x4000005du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ +#define SDLK_KP_6 0x4000005eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ +#define SDLK_KP_7 0x4000005fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ +#define SDLK_KP_8 0x40000060u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ +#define SDLK_KP_9 0x40000061u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ +#define SDLK_KP_0 0x40000062u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ +#define SDLK_KP_PERIOD 0x40000063u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ +#define SDLK_APPLICATION 0x40000065u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ +#define SDLK_POWER 0x40000066u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ +#define SDLK_KP_EQUALS 0x40000067u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ +#define SDLK_F13 0x40000068u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ +#define SDLK_F14 0x40000069u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ +#define SDLK_F15 0x4000006au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ +#define SDLK_F16 0x4000006bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ +#define SDLK_F17 0x4000006cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ +#define SDLK_F18 0x4000006du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ +#define SDLK_F19 0x4000006eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ +#define SDLK_F20 0x4000006fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ +#define SDLK_F21 0x40000070u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ +#define SDLK_F22 0x40000071u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ +#define SDLK_F23 0x40000072u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ +#define SDLK_F24 0x40000073u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ +#define SDLK_EXECUTE 0x40000074u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ +#define SDLK_HELP 0x40000075u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ +#define SDLK_MENU 0x40000076u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ +#define SDLK_SELECT 0x40000077u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ +#define SDLK_STOP 0x40000078u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ +#define SDLK_AGAIN 0x40000079u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ +#define SDLK_UNDO 0x4000007au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ +#define SDLK_CUT 0x4000007bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ +#define SDLK_COPY 0x4000007cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ +#define SDLK_PASTE 0x4000007du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ +#define SDLK_FIND 0x4000007eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ +#define SDLK_MUTE 0x4000007fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ +#define SDLK_VOLUMEUP 0x40000080u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ +#define SDLK_VOLUMEDOWN 0x40000081u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ +#define SDLK_KP_COMMA 0x40000085u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ +#define SDLK_KP_EQUALSAS400 0x40000086u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ +#define SDLK_ALTERASE 0x40000099u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ +#define SDLK_SYSREQ 0x4000009au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ +#define SDLK_CANCEL 0x4000009bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ +#define SDLK_CLEAR 0x4000009cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ +#define SDLK_PRIOR 0x4000009du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ +#define SDLK_RETURN2 0x4000009eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ +#define SDLK_SEPARATOR 0x4000009fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ +#define SDLK_OUT 0x400000a0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ +#define SDLK_OPER 0x400000a1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ +#define SDLK_CLEARAGAIN 0x400000a2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ +#define SDLK_CRSEL 0x400000a3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ +#define SDLK_EXSEL 0x400000a4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ +#define SDLK_KP_00 0x400000b0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ +#define SDLK_KP_000 0x400000b1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ +#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ +#define SDLK_DECIMALSEPARATOR 0x400000b3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ +#define SDLK_CURRENCYUNIT 0x400000b4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ +#define SDLK_CURRENCYSUBUNIT 0x400000b5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ +#define SDLK_KP_LEFTPAREN 0x400000b6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ +#define SDLK_KP_RIGHTPAREN 0x400000b7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ +#define SDLK_KP_LEFTBRACE 0x400000b8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ +#define SDLK_KP_RIGHTBRACE 0x400000b9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ +#define SDLK_KP_TAB 0x400000bau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ +#define SDLK_KP_BACKSPACE 0x400000bbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ +#define SDLK_KP_A 0x400000bcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ +#define SDLK_KP_B 0x400000bdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ +#define SDLK_KP_C 0x400000beu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ +#define SDLK_KP_D 0x400000bfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ +#define SDLK_KP_E 0x400000c0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ +#define SDLK_KP_F 0x400000c1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ +#define SDLK_KP_XOR 0x400000c2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ +#define SDLK_KP_POWER 0x400000c3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ +#define SDLK_KP_PERCENT 0x400000c4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ +#define SDLK_KP_LESS 0x400000c5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ +#define SDLK_KP_GREATER 0x400000c6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ +#define SDLK_KP_AMPERSAND 0x400000c7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ +#define SDLK_KP_DBLAMPERSAND 0x400000c8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ +#define SDLK_KP_VERTICALBAR 0x400000c9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ +#define SDLK_KP_DBLVERTICALBAR 0x400000cau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ +#define SDLK_KP_COLON 0x400000cbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ +#define SDLK_KP_HASH 0x400000ccu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ +#define SDLK_KP_SPACE 0x400000cdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ +#define SDLK_KP_AT 0x400000ceu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ +#define SDLK_KP_EXCLAM 0x400000cfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ +#define SDLK_KP_MEMSTORE 0x400000d0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ +#define SDLK_KP_MEMRECALL 0x400000d1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ +#define SDLK_KP_MEMCLEAR 0x400000d2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ +#define SDLK_KP_MEMADD 0x400000d3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ +#define SDLK_KP_MEMSUBTRACT 0x400000d4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ +#define SDLK_KP_MEMMULTIPLY 0x400000d5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ +#define SDLK_KP_MEMDIVIDE 0x400000d6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ +#define SDLK_KP_PLUSMINUS 0x400000d7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ +#define SDLK_KP_CLEAR 0x400000d8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ +#define SDLK_KP_CLEARENTRY 0x400000d9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ +#define SDLK_KP_BINARY 0x400000dau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ +#define SDLK_KP_OCTAL 0x400000dbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ +#define SDLK_KP_DECIMAL 0x400000dcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ +#define SDLK_KP_HEXADECIMAL 0x400000ddu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ +#define SDLK_LCTRL 0x400000e0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ +#define SDLK_LSHIFT 0x400000e1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ +#define SDLK_LALT 0x400000e2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ +#define SDLK_LGUI 0x400000e3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ +#define SDLK_RCTRL 0x400000e4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ +#define SDLK_RSHIFT 0x400000e5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ +#define SDLK_RALT 0x400000e6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ +#define SDLK_RGUI 0x400000e7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ +#define SDLK_MODE 0x40000101u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ +#define SDLK_SLEEP 0x40000102u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ +#define SDLK_WAKE 0x40000103u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ +#define SDLK_CHANNEL_INCREMENT 0x40000104u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ +#define SDLK_CHANNEL_DECREMENT 0x40000105u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ +#define SDLK_MEDIA_PLAY 0x40000106u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ +#define SDLK_MEDIA_PAUSE 0x40000107u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ +#define SDLK_MEDIA_RECORD 0x40000108u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ +#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ +#define SDLK_MEDIA_REWIND 0x4000010au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ +#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ +#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ +#define SDLK_MEDIA_STOP 0x4000010du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ +#define SDLK_MEDIA_EJECT 0x4000010eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ +#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ +#define SDLK_MEDIA_SELECT 0x40000110u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ +#define SDLK_AC_NEW 0x40000111u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ +#define SDLK_AC_OPEN 0x40000112u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ +#define SDLK_AC_CLOSE 0x40000113u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ +#define SDLK_AC_EXIT 0x40000114u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ +#define SDLK_AC_SAVE 0x40000115u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ +#define SDLK_AC_PRINT 0x40000116u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ +#define SDLK_AC_PROPERTIES 0x40000117u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ +#define SDLK_AC_SEARCH 0x40000118u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ +#define SDLK_AC_HOME 0x40000119u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ +#define SDLK_AC_BACK 0x4000011au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ +#define SDLK_AC_FORWARD 0x4000011bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ +#define SDLK_AC_STOP 0x4000011cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ +#define SDLK_AC_REFRESH 0x4000011du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ +#define SDLK_AC_BOOKMARKS 0x4000011eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ +#define SDLK_SOFTLEFT 0x4000011fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ +#define SDLK_SOFTRIGHT 0x40000120u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ +#define SDLK_CALL 0x40000121u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ +#define SDLK_ENDCALL 0x40000122u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_LEFT_TAB 0x20000001u /**< Extended key Left Tab */ +#define SDLK_LEVEL5_SHIFT 0x20000002u /**< Extended key Level 5 Shift */ +#define SDLK_MULTI_KEY_COMPOSE 0x20000003u /**< Extended key Multi-key Compose */ +#define SDLK_LMETA 0x20000004u /**< Extended key Left Meta */ +#define SDLK_RMETA 0x20000005u /**< Extended key Right Meta */ +#define SDLK_LHYPER 0x20000006u /**< Extended key Left Hyper */ +#define SDLK_RHYPER 0x20000007u /**< Extended key Right Hyper */ /** * Valid key modifiers (possibly OR'd together). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint16 SDL_Keymod; #define SDL_KMOD_NONE 0x0000u /**< no modifier is applicable. */ #define SDL_KMOD_LSHIFT 0x0001u /**< the left Shift key is down. */ #define SDL_KMOD_RSHIFT 0x0002u /**< the right Shift key is down. */ +#define SDL_KMOD_LEVEL5 0x0004u /**< the Level 5 Shift key is down. */ #define SDL_KMOD_LCTRL 0x0040u /**< the left Ctrl (Control) key is down. */ #define SDL_KMOD_RCTRL 0x0080u /**< the right Ctrl (Control) key is down. */ #define SDL_KMOD_LALT 0x0100u /**< the left Alt key is down. */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_loadso.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_loadso.h index ab34a38..f8649d7 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_loadso.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_loadso.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ * * System-dependent library loading routines. * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * * Some things to keep in mind: * * - These functions only work on C function names. Other languages may have @@ -38,6 +46,11 @@ * not defined whether or not it goes into the global symbol namespace for * the application. If it does and it conflicts with symbols in your code or * other shared libraries, you will not get the results you expect. :) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that pointer after the library unloads. */ #ifndef SDL_loadso_h_ @@ -52,6 +65,17 @@ extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * @@ -59,12 +83,14 @@ extern "C" { * \returns an opaque pointer to the object handle or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -86,22 +112,29 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); * \returns a pointer to the function or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_locale.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_locale.h index 85d7750..902843e 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_locale.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_locale.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategoryLocale * * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. */ #ifndef SDL_locale_h @@ -47,7 +53,7 @@ extern "C" { * would be "en"), and the country, if not NULL, will be an ISO-3166 country * code (so Canada would be "CA"). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPreferredLocales */ @@ -96,7 +102,7 @@ typedef struct SDL_Locale * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_log.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_log.h index deda238..a56476c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_log.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_log.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,7 @@ /** * # CategoryLog * - * Simple log messages with priorities and categories. A message’s + * Simple log messages with priorities and categories. A message's * SDL_LogPriority signifies how important the message is. A message's * SDL_LogCategory signifies from what domain it belongs to. Every category * has a minimum priority specified: when a message belongs to that category, @@ -76,7 +76,7 @@ extern "C" { * level, the assert category is enabled at the WARN level, test is enabled at * the VERBOSE level and all other categories are enabled at the ERROR level. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogCategory { @@ -87,12 +87,11 @@ typedef enum SDL_LogCategory SDL_LOG_CATEGORY_AUDIO, SDL_LOG_CATEGORY_VIDEO, SDL_LOG_CATEGORY_RENDER, - SDL_LOG_CATEGORY_GPU, SDL_LOG_CATEGORY_INPUT, SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, SDL_LOG_CATEGORY_RESERVED2, SDL_LOG_CATEGORY_RESERVED3, SDL_LOG_CATEGORY_RESERVED4, @@ -117,17 +116,19 @@ typedef enum SDL_LogCategory /** * The predefined log priorities * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogPriority { - SDL_LOG_PRIORITY_VERBOSE = 1, + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, SDL_LOG_PRIORITY_DEBUG, SDL_LOG_PRIORITY_INFO, SDL_LOG_PRIORITY_WARN, SDL_LOG_PRIORITY_ERROR, SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES + SDL_LOG_PRIORITY_COUNT } SDL_LogPriority; @@ -136,7 +137,9 @@ typedef enum SDL_LogPriority * * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriority @@ -149,14 +152,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); * \param category the category to assign a priority to. * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetLogPriority * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriorities */ -extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, - SDL_LogPriority priority); +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); /** * Get the priority of a particular log category. @@ -164,7 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, * \param category the category to query. * \returns the SDL_LogPriority for the requested category. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriority */ @@ -175,7 +181,9 @@ extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); * * This is called by SDL_Quit(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority @@ -192,15 +200,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); * \param priority the SDL_LogPriority to modify. * \param prefix the prefix to use for that log priority, or NULL to use no * prefix. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); /** * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. @@ -209,7 +219,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \param ... additional parameters matching % tokens in the `fmt` string, if * any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LogCritical * \sa SDL_LogDebug @@ -217,11 +229,37 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * @@ -230,7 +268,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -251,7 +291,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -259,6 +301,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -272,7 +315,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -280,6 +325,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogError * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -293,7 +339,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -302,6 +350,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose */ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); @@ -314,7 +363,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -322,6 +373,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -335,7 +387,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogDebug @@ -343,6 +397,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -357,7 +412,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -365,6 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -380,7 +438,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \param fmt a printf() style message format string. * \param ap a variable argument list. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -388,6 +448,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessage + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -398,7 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, /** * The prototype for the log output callback function. * - * This function is called by SDL when there is new text to be logged. + * This function is called by SDL when there is new text to be logged. A mutex + * is held so that this function is never called by more than one thread at + * once. * * \param userdata what was passed as `userdata` to * SDL_SetLogOutputFunction(). @@ -406,10 +469,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, * \param priority the priority of the message. * \param message the message being output. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void); + /** * Get the current log output function. * @@ -418,8 +495,11 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * \param userdata a pointer filled in with the pointer that is passed to * `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_SetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata); @@ -430,8 +510,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction * \param callback an SDL_LogOutputFunction to call instead of the default. * \param userdata a pointer that is passed to `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_GetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main.h index de3c187..2e7a2eb 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,13 +22,29 @@ /** * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() if necessary so that it is called by SDL. * - * For details on how SDL_main works, and how to use it, please refer to: + * In order to make this consistent on all platforms, the application's main() + * should look like this: + * + * ```c + * int main(int argc, char *argv[]) + * { + * } + * ``` + * + * SDL will take care of platform specific details on how it gets called. + * + * This is also where an app can be configured to use the main callbacks, via + * the SDL_MAIN_USE_CALLBACKS macro. + * + * This is a "single-header library," which is to say that including this + * header inserts code into your program, and you should only include it once + * in most cases. SDL.h does not include this header automatically. + * + * For more information, see: * * https://wiki.libsdl.org/SDL3/README/main-functions - * - * (or docs/README-main-functions.md in the SDL source tree) */ #ifndef SDL_main_h_ @@ -39,8 +55,96 @@ #include #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Inform SDL that the app is providing an entry point instead of SDL. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide the + * proper entry point for the platform, and all the other magic details + * needed, like manually calling SDL_SetMainReady. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + */ +#define SDL_MAIN_HANDLED 1 + +/** + * Inform SDL to use the main callbacks instead of main. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide + * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and + * SDL_AppQuit. The app should not provide a `main` function in this case, and + * doing so will likely cause the build to fail. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + * \sa SDL_AppIterate + * \sa SDL_AppQuit + */ +#define SDL_MAIN_USE_CALLBACKS 1 + +/** + * Defined if the target platform offers a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if available, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_AVAILABLE + +/** + * Defined if the target platform _requires_ a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if required, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_NEEDED + +#endif + +#if defined(__has_include) + #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h") + #define SDL_PLATFORM_PRIVATE_MAIN + #endif +#endif + #ifndef SDL_MAIN_HANDLED - #ifdef SDL_PLATFORM_WIN32 + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_private.h" + + #elif defined(SDL_PLATFORM_WIN32) /* On Windows SDL provides WinMain(), which parses the command line and passes the arguments to your main function. @@ -48,20 +152,6 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_WINRT) - /* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - 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 ` - 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 - #elif defined(SDL_PLATFORM_GDK) /* On GDK, SDL provides a main function that initializes the game runtime. @@ -91,8 +181,14 @@ */ #define SDL_MAIN_NEEDED - /* We need to export SDL_main so it can be launched from Java */ - #define SDLMAIN_DECLSPEC SDL_DECLSPEC + /* As this is launched from Java, the real entry point (main() function) + is outside of the the binary built from this code. + This define makes sure that, unlike on other platforms, SDL_main.h + and SDL_main_impl.h export an `SDL_main()` function (to be called + from Java), but don't implement a native `int main(int argc, char* argv[])` + or similar. + */ + #define SDL_MAIN_EXPORTED #elif defined(SDL_PLATFORM_EMSCRIPTEN) /* On Emscripten, SDL provides a main function that converts URL @@ -129,60 +225,36 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_NGAGE) - /* - TODO: not sure if it should be SDL_MAIN_NEEDED, in SDL2 ngage had a - main implementation, but wasn't mentioned in SDL_main.h - */ - #define SDL_MAIN_AVAILABLE - #endif #endif /* SDL_MAIN_HANDLED */ -#ifndef SDLMAIN_DECLSPEC -#define SDLMAIN_DECLSPEC -#endif - -/** - * \file SDL_main.h - * - * The application's main() function must be called with C linkage, - * and should be declared like this: - * - * ```c - * #ifdef __cplusplus - * extern "C" - * #endif - * int main(int argc, char *argv[]) - * { - * } - * ``` - */ #ifdef SDL_WIKI_DOCUMENTATION_SECTION /** - * Inform SDL to use the main callbacks instead of main. + * A macro to tag a main entry point function as exported. * - * SDL does not define this macro, but will check if it is defined when - * including `SDL_main.h`. If defined, SDL will expect the app to provide - * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and - * SDL_AppQuit. The app should not provide a `main` function in this case, and - * doing so will likely cause the build to fail. + * Most platforms don't need this, and the macro will be defined to nothing. + * Some, like Android, keep the entry points in a shared library and need to + * explicitly export the symbols. * - * Please see [README/main-functions](README/main-functions), (or - * docs/README-main-functions.md in the source tree) for a more detailed - * explanation. + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. * - * \since This macro is used by the headers since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit + * \sa SDL_DECLSPEC */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif +#define SDLMAIN_DECLSPEC + +#elif defined(SDL_MAIN_EXPORTED) +/* We need to export SDL_main so it can be launched from external code, + like SDLActivity.java on Android */ +#define SDLMAIN_DECLSPEC SDL_DECLSPEC +#else +/* usually this is empty */ +#define SDLMAIN_DECLSPEC +#endif /* SDL_MAIN_EXPORTED */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main @@ -248,6 +320,8 @@ extern "C" { * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code * that reports success to the platform. * + * This function is called by SDL on the main thread. + * * \param appstate a place where the app can optionally store a pointer for * future use. * \param argc the standard ANSI C main's argc; number of elements in `argv`. @@ -256,9 +330,7 @@ extern "C" { * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppIterate * \sa SDL_AppEvent @@ -301,13 +373,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int a * SDL_AppQuit and terminates with an exit code that reports success to the * platform. * + * This function is called by SDL on the main thread. + * * \param appstate an optional pointer, provided by the app in SDL_AppInit. * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with SDL_AppEvent() + * for events not pushed on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppEvent @@ -320,15 +395,15 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a * standard "main" function, you should not supply this. * - * This function is called as needed by SDL after SDL_AppInit returns 0; It is - * called once for each new event. + * This function is called as needed by SDL after SDL_AppInit returns + * SDL_APP_CONTINUE. It is called once for each new event. * * There is (currently) no guarantee about what thread this will be called * from; whatever thread pushes an event onto SDL's queue will trigger this * function. SDL is responsible for pumping the event queue between each call * to SDL_AppIterate, so in normal operation one should only get events in a * serial fashion, but be careful if you have a thread that explicitly calls - * SDL_PushEvent. + * SDL_PushEvent. SDL itself will push events to the queue on the main thread. * * Events sent to this function are not owned by the app; if you need to save * the data, you should copy it. @@ -352,14 +427,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with + * SDL_AppIterate() or SDL_AppQuit() for events not pushed from + * the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppIterate */ -extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); /** * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -385,15 +462,19 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const * function call is the last time this pointer will be provided, so any * resources to it should be cleaned up here. * + * This function is called by SDL on the main thread. + * * \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. + * \threadsafety SDL_AppEvent() may get called concurrently with this function + * if other threads that push events are still active. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.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 */ @@ -407,7 +488,7 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate); * program completion, and small non-zero values are considered * errors. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); @@ -440,7 +521,7 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); * * \threadsafety This is the program entry point. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); @@ -453,7 +534,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); * will not be changed it is necessary to define SDL_MAIN_HANDLED before * including SDL.h. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init */ @@ -485,7 +566,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); * \threadsafety Generally this is called once, near startup, from the * process's initial thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved); @@ -512,12 +593,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func * \threadsafety It is not safe to call this anywhere except as the only * function call in SDL_main. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) /** * Register a win32 window class for SDL's use. @@ -538,12 +619,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * what is specified here. * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL * will use `GetModuleHandle(NULL)` instead. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); /** * Deregister the win32 window class from an SDL_RegisterApp call. @@ -558,23 +639,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 st * deregistered when the registration counter in SDL_RegisterApp decrements to * zero through calls to this function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ - -#ifdef SDL_PLATFORM_GDK +#endif /* defined(SDL_PLATFORM_WINDOWS) */ /** * Callback from the application to let the suspend continue. * - * \since This function is available since SDL 3.0.0. + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); -#endif /* SDL_PLATFORM_GDK */ - #ifdef __cplusplus } #endif @@ -583,29 +663,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) /* include header-only SDL_main implementations */ - #if defined(SDL_MAIN_USE_CALLBACKS) \ - || defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ - || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) \ - || defined(SDL_PLATFORM_EMSCRIPTEN) - + #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) /* platforms which main (-equivalent) can be implemented in plain C */ #include - - #elif defined(SDL_PLATFORM_WINRT) /* C++ platforms */ - #ifdef __cplusplus - #include - #else - /* Note: to get rid of the following warning, you can #define SDL_MAIN_NOIMPL before including SDL_main.h - * in your C sourcefile that contains the standard main. Do *not* use SDL_MAIN_HANDLED for that, then SDL_main won't find your main()! - */ - #ifdef _MSC_VER - #pragma message("Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C (then continue including SDL_main.h there!) and create a fresh .cpp file that only contains #include ") - #elif defined(__GNUC__) /* gcc, clang, mingw and compatible are matched by this and have #warning */ - #warning "Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C and create a fresh .cpp file that only contains #include " - #endif /* __GNUC__ */ - #endif /* __cplusplus */ - - #endif /* C++ platforms like SDL_PLATFORM_WINRT etc */ + #endif #endif #endif /* SDL_main_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main_impl.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main_impl.h index ad122df..14ebb42 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main_impl.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_main_impl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,7 +29,7 @@ #endif /* if someone wants to include SDL_main.h but doesn't want the main handing magic, - (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first + (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first. SDL_MAIN_NOIMPL is for SDL-internal usage (only affects implementation, not definition of SDL_MAIN_AVAILABLE etc in SDL_main.h) and if the user wants to have the SDL_main implementation (from this header) in another source file @@ -64,10 +64,15 @@ #endif /* SDL_MAIN_USE_CALLBACKS */ - /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */ - #if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) + /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point, + unless the real entry point needs to be somewhere else entirely, like Android where it's in Java code */ + #if (!defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)) && !defined(SDL_MAIN_EXPORTED) - #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_impl_private.h" + + #elif defined(SDL_PLATFORM_WINDOWS) /* these defines/typedefs are needed for the WinMain() definition */ #ifndef WINAPI @@ -82,7 +87,7 @@ #if defined(_MSC_VER) && !defined(SDL_PLATFORM_GDK) /* This is where execution begins [console apps] */ - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int wmain(int argc, wchar_t *wargv[], wchar_t *wenvp) { (void)argc; @@ -107,7 +112,7 @@ extern "C" { #endif - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw) #else /* ANSI */ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw) @@ -124,83 +129,7 @@ } /* extern "C" */ #endif - /* end of SDL_PLATFORM_WIN32 and SDL_PLATFORM_GDK impls */ - - #elif defined(SDL_PLATFORM_WINRT) - - /* WinRT main based on SDL_winrt_main_NonXAML.cpp, placed in the public domain by David Ludwig 3/13/14 */ - - #include - - /* At least one file in any SDL/WinRT app appears to require compilation - with C++/CX, otherwise a Windows Metadata file won't get created, and - an APPX0702 build error can appear shortly after linking. - - The following set of preprocessor code forces this file to be compiled - as C++/CX, which appears to cause Visual C++ 2012's build tools to - create this .winmd file, and will help allow builds of SDL/WinRT apps - to proceed without error. - - If other files in an app's project enable C++/CX compilation, then it might - be possible for the .cpp file including SDL_main.h to be compiled without /ZW, - for Visual C++'s build tools to create a winmd file, and for the app to - build without APPX0702 errors. In this case, if - SDL_WINRT_METADATA_FILE_AVAILABLE is defined as a C/C++ macro, then - the #error (to force C++/CX compilation) will be disabled. - - Please note that /ZW can be specified on a file-by-file basis. To do this, - right click on the file in Visual C++, click Properties, then change the - setting through the dialog that comes up. - */ - #ifndef SDL_WINRT_METADATA_FILE_AVAILABLE - #if !defined(__cplusplus) || (!defined(__cplusplus_winrt) && _MSVC_LANG < 202002L) - #error The C++ file that includes SDL_main.h must be compiled as C++ code with /ZW, otherwise build errors due to missing .winmd files can occur. - #endif - #endif - - /* Prevent MSVC++ from warning about threading models when defining our - custom WinMain. The threading model will instead be set via a direct - call to Windows::Foundation::Initialize (rather than via an attributed - function). - - To note, this warning (C4447) does not seem to come up unless this file - is compiled with C++/CX enabled (via the /ZW compiler flag). - */ - #ifdef _MSC_VER - #pragma warning(disable : 4447) - /* Make sure the function to initialize the Windows Runtime gets linked in. */ - #pragma comment(lib, "runtimeobject.lib") - #endif - - #ifdef __cplusplus - extern "C" { - #endif - int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int) - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - #if _MSVC_LANG >= 202002L - int main(int argc, char** argv) { - return SDL_RunApp(argc, argv, SDL_main, NULL); - } - #endif - #ifdef __cplusplus - } /* extern "C" */ - #endif - - /* end of WinRT impl */ - - #elif defined(SDL_PLATFORM_NGAGE) - /* same typedef as in ngage SDKs e32def.h */ - typedef signed int TInt; - /* TODO: if it turns out that this only works when built as C++, - move SDL_PLATFORM_NGAGE into the C++ section in SDL_main.h */ - TInt E32Main() - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - - /* end of SDL_PLATFORM_NGAGE impl */ + /* end of SDL_PLATFORM_WINDOWS impls */ #else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ int main(int argc, char *argv[]) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_messagebox.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_messagebox.h index c626b22..365ae36 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_messagebox.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_messagebox.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryMessagebox * - * Message box support routines. + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. */ #ifndef SDL_messagebox_h_ @@ -39,11 +50,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. + * Message box flags. * * If supported will display warning icon, etc. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxFlags; @@ -56,7 +67,7 @@ typedef Uint32 SDL_MessageBoxFlags; /** * SDL_MessageBoxButtonData flags. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxButtonFlags; @@ -66,7 +77,7 @@ typedef Uint32 SDL_MessageBoxButtonFlags; /** * Individual button data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxButtonData { @@ -78,7 +89,7 @@ typedef struct SDL_MessageBoxButtonData /** * RGB value used in a message box color scheme * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColor { @@ -96,23 +107,23 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX /**< Size of the colors array of SDL_MessageBoxColorScheme. */ + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** * A set of colors to use for message box dialogs * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** * MessageBox structure containing title, text, window, etc. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxData { @@ -154,14 +165,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowSimpleMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -193,17 +204,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData * to stderr if you can. * * \param flags an SDL_MessageBoxFlags value. - * \param title uTF-8 title text. - * \param message uTF-8 message text. + * \param title UTF-8 title text. + * \param message UTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_metal.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_metal.h index 7c9aece..14b1bc8 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_metal.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_metal.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,10 @@ * # CategoryMetal * * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. */ #ifndef SDL_metal_h_ @@ -39,7 +43,7 @@ extern "C" { /** * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_MetalView; @@ -61,7 +65,7 @@ typedef void *SDL_MetalView; * \param window the window. * \returns handle NSView or UIView. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_DestroyView * \sa SDL_Metal_GetLayer @@ -76,7 +80,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *windo * * \param view the SDL_MetalView object. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ @@ -88,7 +92,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); * \param view the SDL_MetalView object. * \returns a pointer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_misc.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_misc.h index 23317e0..3dd6fcd 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_misc.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_misc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -62,12 +62,12 @@ extern "C" { * * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mouse.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mouse.h index 90c8560..18856e2 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mouse.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mouse.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,36 @@ /** * # CategoryMouse * - * SDL mouse handling. + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. */ #ifndef SDL_mouse_h_ @@ -30,6 +59,7 @@ #include #include +#include #include #include @@ -46,7 +76,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MouseID; @@ -55,14 +85,14 @@ typedef Uint32 SDL_MouseID; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Cursor SDL_Cursor; /** * Cursor types for SDL_CreateSystemCursor(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemCursor { @@ -86,13 +116,13 @@ typedef enum SDL_SystemCursor SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ - SDL_NUM_SYSTEM_CURSORS + SDL_SYSTEM_CURSOR_COUNT } SDL_SystemCursor; /** * Scroll direction types for the Scroll event * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MouseWheelDirection { @@ -109,7 +139,7 @@ typedef enum SDL_MouseWheelDirection * - Button 4: Side mouse button 1 * - Button 5: Side mouse button 2 * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetMouseState * \sa SDL_GetGlobalMouseState @@ -123,12 +153,12 @@ typedef Uint32 SDL_MouseButtonFlags; #define SDL_BUTTON_X1 4 #define SDL_BUTTON_X2 5 -#define SDL_BUTTON(X) (1u << ((X)-1)) -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) /* Function prototypes */ @@ -136,13 +166,15 @@ typedef Uint32 SDL_MouseButtonFlags; /** * Return whether a mouse is currently connected. * - * \returns SDL_TRUE if a mouse is connected, SDL_FALSE otherwise. + * \returns true if a mouse is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); /** * Get a list of currently connected mice. @@ -158,7 +190,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseNameForID * \sa SDL_HasMouse @@ -174,7 +208,9 @@ extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count); * \returns the name of the selected mouse, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ @@ -185,26 +221,39 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta * * \returns the window with mouse focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); /** - * Retrieve the current state of the mouse. + * Query SDL's cache for the synchronous mouse button state and the + * window-relative SDL-cursor position. * - * The current button state is returned as a button bitmask, which can be - * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse cursor position relative to the focus window. You can pass NULL for - * either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x the x coordinate of the mouse cursor position relative to the - * focus window. - * \param y the y coordinate of the mouse cursor position relative to the - * focus window. - * \returns a 32-bit button bitmask of the current button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the focused window. + * + * In Relative Mode, the SDL-cursor's position usually contradicts the + * platform-cursor's position as manually calculated from + * SDL_GetGlobalMouseState() and SDL_GetWindowPosition. + * + * \param x a pointer to receive the SDL-cursor's x-position from the focused + * window's top left corner, can be NULL if unused. + * \param y a pointer to receive the SDL-cursor's y-position from the focused + * window's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState * \sa SDL_GetRelativeMouseState @@ -212,51 +261,74 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y); /** - * Get the current state of the mouse in relation to the desktop. + * Query the platform for the asynchronous mouse button state and the + * desktop-relative platform-cursor position. * - * This works similarly to SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if you - * need to track the mouse outside of a specific window and SDL_CaptureMouse() - * doesn't fit your needs. For example, it could be useful if you need to - * track the mouse while dragging a window, where coordinates relative to a - * window might not be in sync at all times. + * This function immediately queries the platform for the most recent + * asynchronous state, more costly than retrieving SDL's cached state in + * SDL_GetMouseState(). * - * Note: SDL_GetMouseState() returns the mouse position as SDL understands it - * from the last pump of the event queue. This function, however, queries the - * OS for the current mouse position, and as such, might be a slightly less - * efficient function. Unless you know what you're doing and have a good - * reason to use this function, you probably want SDL_GetMouseState() instead. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the desktop. * - * \param x filled in with the current X coord relative to the desktop; can be - * NULL. - * \param y filled in with the current Y coord relative to the desktop; can be - * NULL. - * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. + * In Relative Mode, the platform-cursor's position usually contradicts the + * SDL-cursor's position as manually calculated from SDL_GetMouseState() and + * SDL_GetWindowPosition. * - * \since This function is available since SDL 3.0.0. + * This function can be useful if you need to track the mouse outside of a + * specific window and SDL_CaptureMouse() doesn't fit your needs. For example, + * it could be useful if you need to track the mouse while dragging a window, + * where coordinates relative to a window might not be in sync at all times. + * + * \param x a pointer to receive the platform-cursor's x-position from the + * desktop's top left corner, can be NULL if unused. + * \param y a pointer to receive the platform-cursor's y-position from the + * desktop's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CaptureMouse * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y); /** - * Retrieve the relative state of the mouse. + * Query SDL's cache for the synchronous mouse button state and accumulated + * mouse delta since last call. * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x a pointer filled with the last recorded x coordinate of the mouse. - * \param y a pointer filled with the last recorded y coordinate of the mouse. - * \returns a 32-bit button bitmask of the relative button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y deltas accumulated since the last call to this function + * (or since event initialization). + * + * This function is useful for reducing overhead by processing relative mouse + * inputs in one go per-frame instead of individually per-event, at the + * expense of losing the order between events within the frame (e.g. quickly + * pressing and releasing a button within the same frame). + * + * \param x a pointer to receive the x mouse delta accumulated since last + * call, can be NULL if unused. + * \param y a pointer to receive the y mouse delta accumulated since last + * call, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y); @@ -275,7 +347,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float * \param x the x coordinate within the window. * \param y the y coordinate within the window. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseGlobal */ @@ -295,14 +369,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * * \param x the x coordinate. * \param y the y coordinate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseInWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); /** * Set relative mouse mode for a window. @@ -312,31 +388,39 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * report continuous relative mouse motion even if the mouse is at the edge of * the window. * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * * This function will flush any pending mouse motion for this window. * * \param window the window to change. - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); /** * Query whether relative mouse mode is enabled for a window. * * \param window the window to query. - * \returns SDL_TRUE if relative mode is enabled for a window or SDL_FALSE - * otherwise. + * \returns true if relative mode is enabled for a window or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); /** * Capture the mouse and to track input outside an SDL window. @@ -374,15 +458,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window * * app, you can disable auto capture by setting the * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); /** * Create a cursor using the specified bitmap data and mask (in MSB format). @@ -419,7 +505,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); * \returns a new cursor with the specified parameters on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateSystemCursor @@ -450,7 +538,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data, * \returns the new cursor on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCursor * \sa SDL_CreateSystemCursor @@ -468,7 +558,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyCursor */ @@ -483,14 +575,16 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * this is desired for any reason. * * \param cursor a cursor to make active. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); /** * Get the active cursor. @@ -500,7 +594,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); * * \returns the active cursor or NULL if there is no mouse. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetCursor */ @@ -515,7 +611,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void); * \returns the default cursor on success or NULL on failuree; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); @@ -527,7 +625,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); * * \param cursor the cursor to free. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateCursor @@ -538,41 +638,47 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); /** * Show the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_HideCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); /** * Hide the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); /** * Return whether the cursor is currently being shown. * - * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the - * cursor is hidden. + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideCursor * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mutex.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mutex.h index 3a7ce56..c88ec15 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mutex.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_mutex.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,84 +25,245 @@ /** * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. */ #include +#include #include +#include -/******************************************************************************/ -/* Enable thread safety attributes only with clang. +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Enable thread safety attributes, only with clang. + * * The attributes can be safely erased when compiling with other compilers. * * To enable analysis, set these environment variables before running cmake: - * export CC=clang - * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` */ -#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ - defined(__clang__) && (!defined(SWIG)) +#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) + +#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG)) #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) #else #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ #endif +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SCOPED_CAPABILITY \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PT_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_BEFORE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_AFTER(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_GENERIC(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE_SHARED(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_EXCLUDES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_SHARED_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RETURN_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) @@ -130,7 +291,7 @@ extern "C" { * * https://en.wikipedia.org/wiki/Mutex * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Mutex SDL_Mutex; @@ -147,7 +308,7 @@ typedef struct SDL_Mutex SDL_Mutex; * \returns the initialized and unlocked mutex or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyMutex * \sa SDL_LockMutex @@ -173,7 +334,7 @@ extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); * * \param mutex the mutex to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockMutex * \sa SDL_UnlockMutex @@ -184,22 +345,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * Try to lock a mutex without blocking. * * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns SDL_FALSE immediately. + * this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. * - * This function returns SDL_TRUE if passed a NULL mutex. + * This function returns true if passed a NULL mutex. * * \param mutex the mutex to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the mutex would block. + * \returns true on success, false if the mutex would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_UnlockMutex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); /** * Unlock the mutex. @@ -213,7 +374,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ * * \param mutex the mutex to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_TryLockMutex @@ -231,7 +392,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m * * \param mutex the mutex to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateMutex */ @@ -261,7 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); * about how threads are scheduled and when they can be recursively locked. * These are documented in the other rwlock functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_RWLock SDL_RWLock; @@ -296,7 +457,7 @@ typedef struct SDL_RWLock SDL_RWLock; * \returns the initialized and unlocked read/write lock or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRWLock * \sa SDL_LockRWLockForReading @@ -336,7 +497,7 @@ extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading @@ -367,7 +528,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting @@ -379,7 +540,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Try to lock a read/write lock _for reading_ without blocking. * * This works just like SDL_LockRWLockForReading(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need access to a resource but don't want to * wait for it, and will return to it to try again later. @@ -387,24 +548,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Trying to lock for read-only access can succeed if other threads are * holding read-only locks, as this won't prevent access. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); /** * Try to lock a read/write lock _for writing_ without blocking. * * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. @@ -417,18 +578,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwl * read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock before requesting a write lock. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); /** * Unlock the read/write lock. @@ -446,7 +607,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwl * * \param rwlock the rwlock to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_LockRWLockForWriting @@ -466,7 +627,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS * * \param rwlock the rwlock to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRWLock */ @@ -492,7 +653,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); * * https://en.wikipedia.org/wiki/Semaphore_(programming) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Semaphore SDL_Semaphore; @@ -509,7 +670,7 @@ typedef struct SDL_Semaphore SDL_Semaphore; * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySemaphore * \sa SDL_SignalSemaphore @@ -528,7 +689,7 @@ extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_v * * \param sem the semaphore to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSemaphore */ @@ -546,7 +707,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * * \param sem the semaphore wait on. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore @@ -560,18 +721,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * This function checks to see if the semaphore pointed to by `sem` has a * positive value and atomically decrements the semaphore value if it does. If * the semaphore doesn't have a positive value, the function immediately - * returns SDL_FALSE. + * returns false. * * \param sem the semaphore to wait on. - * \returns SDL_TRUE if the wait succeeds, SDL_FALSE if the wait would block. + * \returns true if the wait succeeds, false if the wait would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. @@ -583,22 +744,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to wait on. * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the wait succeeds or SDL_FALSE if the wait times out. + * \returns true if the wait succeeds or false if the wait times out. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); /** * Atomically increment a semaphore's value and wake waiting threads. * * \param sem the semaphore to increment. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore @@ -612,7 +773,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to query. * \returns the current value of the semaphore. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); @@ -635,7 +796,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); * * https://en.wikipedia.org/wiki/Condition_variable * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Condition SDL_Condition; @@ -645,7 +806,7 @@ typedef struct SDL_Condition SDL_Condition; * \returns a new condition variable or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -660,7 +821,7 @@ extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); * * \param cond the condition variable to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCondition */ @@ -673,7 +834,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_WaitCondition @@ -688,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalCondition * \sa SDL_WaitCondition @@ -716,7 +877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -741,22 +902,167 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mute * \param mutex the mutex used to coordinate thread access. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the condition variable is signaled, SDL_FALSE if the - * condition is not signaled in the allotted time. + * \returns true if the condition variable is signaled, false if the condition + * is not signaled in the allotted time. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition * \sa SDL_WaitCondition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, SDL_Mutex *mutex, Sint32 timeoutMS); /* @} *//* Condition variable functions */ +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * DoQuitTasks(); + * SDL_SetInitialized(&init, false); + * } + * ``` + * + * Note that this doesn't protect any resources created during initialization, + * or guarantee that nobody is using those resources during cleanup. You + * should use other mechanisms to protect those, if that's a concern for your + * code. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_oldnames.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_oldnames.h index 02c881c..c93607e 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_oldnames.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_oldnames.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -38,11 +38,14 @@ #ifdef SDL_ENABLE_OLD_NAMES /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer #define SDL_AtomicLock SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_UnlockSpinlock #define SDL_atomic_t SDL_AtomicInt @@ -74,6 +77,7 @@ #define SDL_NewAudioStream SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -166,14 +170,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -193,7 +196,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -304,6 +307,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -419,9 +424,15 @@ #define SDL_LogSetAllPriority SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK #define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT @@ -558,6 +569,7 @@ #define SDL_WriteLE64 SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -580,7 +592,12 @@ #define SDL_SensorUpdate SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE false #define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtok_r /* ##SDL_surface.h */ @@ -623,14 +640,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iPhoneSetEventPump SDL_SetiOSEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_CleanupTLS #define SDL_TLSGet SDL_GetTLS #define SDL_TLSSet SDL_SetTLS @@ -645,6 +661,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint @@ -661,11 +681,14 @@ #elif !defined(SDL_DISABLE_OLD_NAMES) /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer #define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock #define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt @@ -697,6 +720,7 @@ #define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -789,14 +813,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_WINDOWEVENT_RESTORED_renamed_SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_WINDOWEVENT_SHOWN_renamed_SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_WINDOWEVENT_TAKE_FOCUS_renamed_SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_eventaction_renamed_SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_CONTROLLER_AXIS_RIGHTX_renamed_SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_CONTROLLER_AXIS_RIGHTY_renamed_SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_CONTROLLER_AXIS_TRIGGERLEFT_renamed_SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -816,7 +839,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_CONTROLLER_BUTTON_INVALID_renamed_SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_CONTROLLER_BUTTON_LEFTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_CONTROLLER_BUTTON_LEFTSTICK_renamed_SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_CONTROLLER_BUTTON_MISC1_renamed_SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_CONTROLLER_BUTTON_PADDLE1_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_CONTROLLER_BUTTON_PADDLE2_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -928,6 +951,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE_renamed_SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_LINUX_DIGITAL_HATS_renamed_SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_LINUX_HAT_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_LINUX_JOYSTICK_CLASSIC_renamed_SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -1043,9 +1068,15 @@ #define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK #define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT @@ -1182,6 +1213,7 @@ #define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -1204,7 +1236,12 @@ #define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false #define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r /* ##SDL_surface.h */ @@ -1247,14 +1284,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_WinRTGetDeviceFamily_renamed_SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPathUTF8_renamed_SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback #define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS #define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS #define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS @@ -1269,6 +1305,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DeleteContext_renamed_SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLattr_renamed_SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLcontextFlag_renamed_SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLcontextReleaseFlag_renamed_SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLprofile_renamed_SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestDisplayMode_renamed_SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetDisplayOrientation_renamed_SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengl.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengl.h index 6bdcbe0..d1b8b02 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengl.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -783,6 +783,7 @@ typedef double GLclampd; /* double precision float in [0,1] */ * Miscellaneous */ +#ifndef SDL_OPENGL_1_NO_PROTOTYPES GLAPI void GLAPIENTRY glClearIndex( GLfloat c ); GLAPI void GLAPIENTRY glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); @@ -1480,6 +1481,706 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); + +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); + +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); + +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); + +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); + +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); + +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); + +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); + +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); + +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); + +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); + +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); + +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); + +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); + +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); + +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); + +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); + +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); + + +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + + +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); + +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); + +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); + + +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ + + +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); + +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); + +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); + +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); + +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); + +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); + + +/* + * Depth Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARDEPTHPROC) ( GLclampd depth ); + +typedef void (APIENTRYP PFNGLDEPTHFUNCPROC) ( GLenum func ); + +typedef void (APIENTRYP PFNGLDEPTHMASKPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLDEPTHRANGEPROC) ( GLclampd near_val, GLclampd far_val ); + + +/* + * Accumulation Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARACCUMPROC) ( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha ); + +typedef void (APIENTRYP PFNGLACCUMPROC) ( GLenum op, GLfloat value ); + + +/* + * Transformation + */ + +typedef void (APIENTRYP PFNGLMATRIXMODEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLORTHOPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLFRUSTUMPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLVIEWPORTPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height ); + +typedef void (APIENTRYP PFNGLPUSHMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLPOPMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADIDENTITYPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLLOADMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLMULTMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLMULTMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLROTATEDPROC) ( GLdouble angle, + GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLROTATEFPROC) ( GLfloat angle, + GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLSCALEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLSCALEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLTRANSLATEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLTRANSLATEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + + +/* + * Display Lists + */ + +typedef GLboolean (APIENTRYP PFNGLISLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLDELETELISTSPROC) ( GLuint list, GLsizei range ); + +typedef GLuint (APIENTRYP PFNGLGENLISTSPROC) ( GLsizei range ); + +typedef void (APIENTRYP PFNGLNEWLISTPROC) ( GLuint list, GLenum mode ); + +typedef void (APIENTRYP PFNGLENDLISTPROC) ( void ); + +typedef void (APIENTRYP PFNGLCALLLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLCALLLISTSPROC) ( GLsizei n, GLenum type, + const GLvoid *lists ); + +typedef void (APIENTRYP PFNGLLISTBASEPROC) ( GLuint base ); + + +/* + * Drawing Functions + */ + +typedef void (APIENTRYP PFNGLBEGINPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENDPROC) ( void ); + + +typedef void (APIENTRYP PFNGLVERTEX2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLVERTEX2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLVERTEX2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLVERTEX2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLVERTEX3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLVERTEX3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLVERTEX3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLVERTEX3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLVERTEX4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLVERTEX4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLVERTEX4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLVERTEX4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLVERTEX2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLNORMAL3BPROC) ( GLbyte nx, GLbyte ny, GLbyte nz ); +typedef void (APIENTRYP PFNGLNORMAL3DPROC) ( GLdouble nx, GLdouble ny, GLdouble nz ); +typedef void (APIENTRYP PFNGLNORMAL3FPROC) ( GLfloat nx, GLfloat ny, GLfloat nz ); +typedef void (APIENTRYP PFNGLNORMAL3IPROC) ( GLint nx, GLint ny, GLint nz ); +typedef void (APIENTRYP PFNGLNORMAL3SPROC) ( GLshort nx, GLshort ny, GLshort nz ); + +typedef void (APIENTRYP PFNGLNORMAL3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLNORMAL3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLNORMAL3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLNORMAL3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLNORMAL3SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLINDEXDPROC) ( GLdouble c ); +typedef void (APIENTRYP PFNGLINDEXFPROC) ( GLfloat c ); +typedef void (APIENTRYP PFNGLINDEXIPROC) ( GLint c ); +typedef void (APIENTRYP PFNGLINDEXSPROC) ( GLshort c ); +typedef void (APIENTRYP PFNGLINDEXUBPROC) ( GLubyte c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLINDEXDVPROC) ( const GLdouble *c ); +typedef void (APIENTRYP PFNGLINDEXFVPROC) ( const GLfloat *c ); +typedef void (APIENTRYP PFNGLINDEXIVPROC) ( const GLint *c ); +typedef void (APIENTRYP PFNGLINDEXSVPROC) ( const GLshort *c ); +typedef void (APIENTRYP PFNGLINDEXUBVPROC) ( const GLubyte *c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLCOLOR3BPROC) ( GLbyte red, GLbyte green, GLbyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3DPROC) ( GLdouble red, GLdouble green, GLdouble blue ); +typedef void (APIENTRYP PFNGLCOLOR3FPROC) ( GLfloat red, GLfloat green, GLfloat blue ); +typedef void (APIENTRYP PFNGLCOLOR3IPROC) ( GLint red, GLint green, GLint blue ); +typedef void (APIENTRYP PFNGLCOLOR3SPROC) ( GLshort red, GLshort green, GLshort blue ); +typedef void (APIENTRYP PFNGLCOLOR3UBPROC) ( GLubyte red, GLubyte green, GLubyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3UIPROC) ( GLuint red, GLuint green, GLuint blue ); +typedef void (APIENTRYP PFNGLCOLOR3USPROC) ( GLushort red, GLushort green, GLushort blue ); + +typedef void (APIENTRYP PFNGLCOLOR4BPROC) ( GLbyte red, GLbyte green, + GLbyte blue, GLbyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4DPROC) ( GLdouble red, GLdouble green, + GLdouble blue, GLdouble alpha ); +typedef void (APIENTRYP PFNGLCOLOR4FPROC) ( GLfloat red, GLfloat green, + GLfloat blue, GLfloat alpha ); +typedef void (APIENTRYP PFNGLCOLOR4IPROC) ( GLint red, GLint green, + GLint blue, GLint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4SPROC) ( GLshort red, GLshort green, + GLshort blue, GLshort alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UBPROC) ( GLubyte red, GLubyte green, + GLubyte blue, GLubyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UIPROC) ( GLuint red, GLuint green, + GLuint blue, GLuint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4USPROC) ( GLushort red, GLushort green, + GLushort blue, GLushort alpha ); + + +typedef void (APIENTRYP PFNGLCOLOR3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR3SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR3UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR3USVPROC) ( const GLushort *v ); + +typedef void (APIENTRYP PFNGLCOLOR4BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR4SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR4UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR4USVPROC) ( const GLushort *v ); + + +typedef void (APIENTRYP PFNGLTEXCOORD1DPROC) ( GLdouble s ); +typedef void (APIENTRYP PFNGLTEXCOORD1FPROC) ( GLfloat s ); +typedef void (APIENTRYP PFNGLTEXCOORD1IPROC) ( GLint s ); +typedef void (APIENTRYP PFNGLTEXCOORD1SPROC) ( GLshort s ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DPROC) ( GLdouble s, GLdouble t ); +typedef void (APIENTRYP PFNGLTEXCOORD2FPROC) ( GLfloat s, GLfloat t ); +typedef void (APIENTRYP PFNGLTEXCOORD2IPROC) ( GLint s, GLint t ); +typedef void (APIENTRYP PFNGLTEXCOORD2SPROC) ( GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DPROC) ( GLdouble s, GLdouble t, GLdouble r ); +typedef void (APIENTRYP PFNGLTEXCOORD3FPROC) ( GLfloat s, GLfloat t, GLfloat r ); +typedef void (APIENTRYP PFNGLTEXCOORD3IPROC) ( GLint s, GLint t, GLint r ); +typedef void (APIENTRYP PFNGLTEXCOORD3SPROC) ( GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DPROC) ( GLdouble s, GLdouble t, GLdouble r, GLdouble q ); +typedef void (APIENTRYP PFNGLTEXCOORD4FPROC) ( GLfloat s, GLfloat t, GLfloat r, GLfloat q ); +typedef void (APIENTRYP PFNGLTEXCOORD4IPROC) ( GLint s, GLint t, GLint r, GLint q ); +typedef void (APIENTRYP PFNGLTEXCOORD4SPROC) ( GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLTEXCOORD1DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRASTERPOS2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLRASTERPOS2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLRASTERPOS2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLRASTERPOS2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLRASTERPOS3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLRASTERPOS3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLRASTERPOS3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLRASTERPOS4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLRASTERPOS4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLRASTERPOS4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLRASTERPOS2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRECTDPROC) ( GLdouble x1, GLdouble y1, GLdouble x2, GLdouble y2 ); +typedef void (APIENTRYP PFNGLRECTFPROC) ( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ); +typedef void (APIENTRYP PFNGLRECTIPROC) ( GLint x1, GLint y1, GLint x2, GLint y2 ); +typedef void (APIENTRYP PFNGLRECTSPROC) ( GLshort x1, GLshort y1, GLshort x2, GLshort y2 ); + + +typedef void (APIENTRYP PFNGLRECTDVPROC) ( const GLdouble *v1, const GLdouble *v2 ); +typedef void (APIENTRYP PFNGLRECTFVPROC) ( const GLfloat *v1, const GLfloat *v2 ); +typedef void (APIENTRYP PFNGLRECTIVPROC) ( const GLint *v1, const GLint *v2 ); +typedef void (APIENTRYP PFNGLRECTSVPROC) ( const GLshort *v1, const GLshort *v2 ); + + +/* + * Vertex Arrays (1.1) + */ + +typedef void (APIENTRYP PFNGLVERTEXPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLNORMALPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLCOLORPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLINDEXPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLTEXCOORDPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPOINTERPROC) ( GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLGETPOINTERVPROC) ( GLenum pname, GLvoid **params ); + +typedef void (APIENTRYP PFNGLARRAYELEMENTPROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLDRAWARRAYSPROC) ( GLenum mode, GLint first, GLsizei count ); + +typedef void (APIENTRYP PFNGLDRAWELEMENTSPROC) ( GLenum mode, GLsizei count, + GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLINTERLEAVEDARRAYSPROC) ( GLenum format, GLsizei stride, + const GLvoid *pointer ); + +/* + * Lighting + */ + +typedef void (APIENTRYP PFNGLSHADEMODELPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLLIGHTFPROC) ( GLenum light, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTIPROC) ( GLenum light, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTFVPROC) ( GLenum light, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTIVPROC) ( GLenum light, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETLIGHTFVPROC) ( GLenum light, GLenum pname, + GLfloat *params ); +typedef void (APIENTRYP PFNGLGETLIGHTIVPROC) ( GLenum light, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLLIGHTMODELFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTMODELIPROC) ( GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTMODELFVPROC) ( GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTMODELIVPROC) ( GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLMATERIALFPROC) ( GLenum face, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLMATERIALIPROC) ( GLenum face, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLMATERIALFVPROC) ( GLenum face, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLMATERIALIVPROC) ( GLenum face, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETMATERIALFVPROC) ( GLenum face, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETMATERIALIVPROC) ( GLenum face, GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLCOLORMATERIALPROC) ( GLenum face, GLenum mode ); + + +/* + * Raster functions + */ + +typedef void (APIENTRYP PFNGLPIXELZOOMPROC) ( GLfloat xfactor, GLfloat yfactor ); + +typedef void (APIENTRYP PFNGLPIXELSTOREFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELSTOREIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELTRANSFERFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELTRANSFERIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELMAPFVPROC) ( GLenum map, GLsizei mapsize, + const GLfloat *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUIVPROC) ( GLenum map, GLsizei mapsize, + const GLuint *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUSVPROC) ( GLenum map, GLsizei mapsize, + const GLushort *values ); + +typedef void (APIENTRYP PFNGLGETPIXELMAPFVPROC) ( GLenum map, GLfloat *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUIVPROC) ( GLenum map, GLuint *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUSVPROC) ( GLenum map, GLushort *values ); + +typedef void (APIENTRYP PFNGLBITMAPPROC) ( GLsizei width, GLsizei height, + GLfloat xorig, GLfloat yorig, + GLfloat xmove, GLfloat ymove, + const GLubyte *bitmap ); + +typedef void (APIENTRYP PFNGLREADPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLDRAWPIXELSPROC) ( GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLCOPYPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum type ); + +/* + * Stenciling + */ + +typedef void (APIENTRYP PFNGLSTENCILFUNCPROC) ( GLenum func, GLint ref, GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILOPPROC) ( GLenum fail, GLenum zfail, GLenum zpass ); + +typedef void (APIENTRYP PFNGLCLEARSTENCILPROC) ( GLint s ); + + + +/* + * Texture mapping + */ + +typedef void (APIENTRYP PFNGLTEXGENDPROC) ( GLenum coord, GLenum pname, GLdouble param ); +typedef void (APIENTRYP PFNGLTEXGENFPROC) ( GLenum coord, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXGENIPROC) ( GLenum coord, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXGENDVPROC) ( GLenum coord, GLenum pname, const GLdouble *params ); +typedef void (APIENTRYP PFNGLTEXGENFVPROC) ( GLenum coord, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXGENIVPROC) ( GLenum coord, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXGENDVPROC) ( GLenum coord, GLenum pname, GLdouble *params ); +typedef void (APIENTRYP PFNGLGETTEXGENFVPROC) ( GLenum coord, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXGENIVPROC) ( GLenum coord, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXENVFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXENVIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXENVFVPROC) ( GLenum target, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXENVIVPROC) ( GLenum target, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXENVFVPROC) ( GLenum target, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXENVIVPROC) ( GLenum target, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXPARAMETERFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXPARAMETERFVPROC) ( GLenum target, + GLenum pname, GLfloat *params); +typedef void (APIENTRYP PFNGLGETTEXPARAMETERIVPROC) ( GLenum target, + GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERFVPROC) ( GLenum target, GLint level, + GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERIVPROC) ( GLenum target, GLint level, + GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLint border, GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLGETTEXIMAGEPROC) ( GLenum target, GLint level, + GLenum format, GLenum type, + GLvoid *pixels ); + + +/* 1.1 functions */ + +typedef void (APIENTRYP PFNGLGENTEXTURESPROC) ( GLsizei n, GLuint *textures ); + +typedef void (APIENTRYP PFNGLDELETETEXTURESPROC) ( GLsizei n, const GLuint *textures); + +typedef void (APIENTRYP PFNGLBINDTEXTUREPROC) ( GLenum target, GLuint texture ); + +typedef void (APIENTRYP PFNGLPRIORITIZETEXTURESPROC) ( GLsizei n, + const GLuint *textures, + const GLclampf *priorities ); + +typedef GLboolean (APIENTRYP PFNGLARETEXTURESRESIDENTPROC) ( GLsizei n, + const GLuint *textures, + GLboolean *residences ); + +typedef GLboolean (APIENTRYP PFNGLISTEXTUREPROC) ( GLuint texture ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, + GLsizei width, GLenum format, + GLenum type, const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLsizei height, + GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint x, GLint y, + GLsizei width ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint x, GLint y, + GLsizei width, GLsizei height ); + + +/* + * Evaluators + */ + +typedef void (APIENTRYP PFNGLMAP1DPROC) ( GLenum target, GLdouble u1, GLdouble u2, + GLint stride, + GLint order, const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP1FPROC) ( GLenum target, GLfloat u1, GLfloat u2, + GLint stride, + GLint order, const GLfloat *points ); + +typedef void (APIENTRYP PFNGLMAP2DPROC) ( GLenum target, + GLdouble u1, GLdouble u2, GLint ustride, GLint uorder, + GLdouble v1, GLdouble v2, GLint vstride, GLint vorder, + const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP2FPROC) ( GLenum target, + GLfloat u1, GLfloat u2, GLint ustride, GLint uorder, + GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, + const GLfloat *points ); + +typedef void (APIENTRYP PFNGLGETMAPDVPROC) ( GLenum target, GLenum query, GLdouble *v ); +typedef void (APIENTRYP PFNGLGETMAPFVPROC) ( GLenum target, GLenum query, GLfloat *v ); +typedef void (APIENTRYP PFNGLGETMAPIVPROC) ( GLenum target, GLenum query, GLint *v ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DPROC) ( GLdouble u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FPROC) ( GLfloat u ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DPROC) ( GLdouble u, GLdouble v ); +typedef void (APIENTRYP PFNGLEVALCOORD2FPROC) ( GLfloat u, GLfloat v ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD2FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLMAPGRID1DPROC) ( GLint un, GLdouble u1, GLdouble u2 ); +typedef void (APIENTRYP PFNGLMAPGRID1FPROC) ( GLint un, GLfloat u1, GLfloat u2 ); + +typedef void (APIENTRYP PFNGLMAPGRID2DPROC) ( GLint un, GLdouble u1, GLdouble u2, + GLint vn, GLdouble v1, GLdouble v2 ); +typedef void (APIENTRYP PFNGLMAPGRID2FPROC) ( GLint un, GLfloat u1, GLfloat u2, + GLint vn, GLfloat v1, GLfloat v2 ); + +typedef void (APIENTRYP PFNGLEVALPOINT1PROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLEVALPOINT2PROC) ( GLint i, GLint j ); + +typedef void (APIENTRYP PFNGLEVALMESH1PROC) ( GLenum mode, GLint i1, GLint i2 ); + +typedef void (APIENTRYP PFNGLEVALMESH2PROC) ( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + + +/* + * Fog + */ + +typedef void (APIENTRYP PFNGLFOGFPROC) ( GLenum pname, GLfloat param ); + +typedef void (APIENTRYP PFNGLFOGIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLFOGFVPROC) ( GLenum pname, const GLfloat *params ); + +typedef void (APIENTRYP PFNGLFOGIVPROC) ( GLenum pname, const GLint *params ); + + +/* + * Selection and Feedback + */ + +typedef void (APIENTRYP PFNGLFEEDBACKBUFFERPROC) ( GLsizei size, GLenum type, GLfloat *buffer ); + +typedef void (APIENTRYP PFNGLPASSTHROUGHPROC) ( GLfloat token ); + +typedef void (APIENTRYP PFNGLSELECTBUFFERPROC) ( GLsizei size, GLuint *buffer ); + +typedef void (APIENTRYP PFNGLINITNAMESPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPUSHNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPOPNAMEPROC) ( void ); +#endif /* @@ -1528,6 +2229,8 @@ GLAPI void GLAPIENTRY glPopName( void ); #define GL_MAX_3D_TEXTURE_SIZE 0x8073 #define GL_TEXTURE_BINDING_3D 0x806A +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); @@ -1551,6 +2254,34 @@ GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, GLint y, GLsizei width, GLsizei height ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) ( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif + typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); @@ -1638,6 +2369,8 @@ typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, #define GL_BLEND_COLOR 0x8005 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, GLsizei width, GLenum format, GLenum type, const GLvoid *table ); @@ -1746,6 +2479,119 @@ GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +typedef void (APIENTRYP PFNGLCOLORSUBTABLEPROC) ( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERIVPROC) (GLenum target, GLenum pname, + const GLint *params); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERFVPROC) (GLenum target, GLenum pname, + const GLfloat *params); + +typedef void (APIENTRYP PFNGLCOPYCOLORSUBTABLEPROC) ( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLBLENDEQUATIONPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLBLENDCOLORPROC) ( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLHISTOGRAMPROC) ( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETHISTOGRAMPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLMINMAXPROC) ( GLenum target, GLenum internalformat, + GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETMINMAXPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETMINMAXPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFPROC) ( GLenum target, GLenum pname, + GLfloat params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIPROC) ( GLenum target, GLenum pname, + GLint params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLSEPARABLEFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +typedef void (APIENTRYP PFNGLGETSEPARABLEFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif + @@ -1858,6 +2704,8 @@ GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, /* texture_border_clamp */ #define GL_CLAMP_TO_BORDER 0x812D +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTexture( GLenum texture ); GLAPI void GLAPIENTRY glClientActiveTexture( GLenum texture ); @@ -1951,6 +2799,104 @@ GLAPI void GLAPIENTRY glMultTransposeMatrixf( const GLfloat m[16] ); GLAPI void GLAPIENTRY glSampleCoverage( GLclampf value, GLboolean invert ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE1DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE2DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE3DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) ( GLenum target, GLint lod, GLvoid *img ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DPROC) ( GLenum target, GLdouble s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FPROC) ( GLenum target, GLfloat s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IPROC) ( GLenum target, GLint s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SPROC) ( GLenum target, GLshort s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DPROC) ( GLenum target, GLdouble s, GLdouble t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FPROC) ( GLenum target, GLfloat s, GLfloat t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IPROC) ( GLenum target, GLint s, GLint t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SPROC) ( GLenum target, GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IPROC) ( GLenum target, GLint s, GLint t, GLint r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IPROC) ( GLenum target, GLint s, GLint t, GLint r, GLint q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVPROC) ( GLenum target, const GLshort *v ); + + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) ( GLclampf value, GLboolean invert ); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) (GLenum texture); typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) (GLclampf value, GLboolean invert); @@ -2006,6 +2952,8 @@ typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) (GLenum target, GLint le #define GL_CLIENT_ACTIVE_TEXTURE_ARB 0x84E1 #define GL_MAX_TEXTURE_UNITS_ARB 0x84E2 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glClientActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glMultiTexCoord1dARB(GLenum target, GLdouble s); @@ -2041,6 +2989,46 @@ GLAPI void GLAPIENTRY glMultiTexCoord4ivARB(GLenum target, const GLint *v); GLAPI void GLAPIENTRY glMultiTexCoord4sARB(GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); GLAPI void GLAPIENTRY glMultiTexCoord4svARB(GLenum target, const GLshort *v); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FARBPROC) (GLenum target, GLfloat s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IARBPROC) (GLenum target, GLint s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SARBPROC) (GLenum target, GLshort s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DARBPROC) (GLenum target, GLdouble s, GLdouble t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FARBPROC) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IARBPROC) (GLenum target, GLint s, GLint t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SARBPROC) (GLenum target, GLshort s, GLshort t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IARBPROC) (GLenum target, GLint s, GLint t, GLint r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IARBPROC) (GLenum target, GLint s, GLint t, GLint r, GLint q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLshort *v); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles.h index bde4d74..4fb9a4b 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles2.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles2.h index ba19601..365898a 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles2.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_opengles2.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pen.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pen.h index cda4f0f..5182eeb 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pen.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pen.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -39,7 +39,9 @@ #ifndef SDL_pen_h_ #define SDL_pen_h_ -#include +#include +#include +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -55,24 +57,39 @@ extern "C" { * consistent as long as SDL can recognize a tool to be the same pen; but if a * pen physically leaves the area and returns, it might get a new ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenID; +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + /** * Pen input flags, as reported by various pen events' `pen_state` field. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenInputFlags; -#define SDL_PEN_INPUT_DOWN (1u << 0) /**< & to see if pen is pressed down */ -#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< & to see if button 1 is pressed */ -#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< & to see if button 2 is pressed */ -#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< & to see if button 3 is pressed */ -#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< & to see if button 4 is pressed */ -#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< & to see if button 5 is pressed */ -#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< & to see if eraser tip is used */ + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ /** * Pen axis indices. @@ -87,20 +104,18 @@ typedef Uint32 SDL_PenInputFlags; * * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PenAxis { SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ - SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). - The physical max/min tilt may be smaller than -90.0 / 90.0, check SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). - The physical max/min tilt may be smaller than -90.0 / 90.0 check SDL_PenCapabilityInfo */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ - SDL_PEN_NUM_AXES /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ } SDL_PenAxis; /* Ends C function definitions when using C++ */ @@ -110,4 +125,3 @@ typedef enum SDL_PenAxis #endif /* SDL_pen_h_ */ -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pixels.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pixels.h index 3825dd5..b6f38ac 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pixels.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_pixels.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,59 @@ /** * # CategoryPixels * - * Pixel management. + * SDL offers facilities for pixel management. + * + * Largely these facilities deal with pixel _format_: what does this set of + * bits represent? + * + * If you mostly want to think of a pixel as some combination of red, green, + * blue, and maybe alpha intensities, this is all pretty straightforward, and + * in many cases, is enough information to build a perfectly fine game. + * + * However, the actual definition of a pixel is more complex than that: + * + * Pixels are a representation of a color in a particular color space. + * + * The first characteristic of a color space is the color type. SDL + * understands two different color types, RGB and YCbCr, or in SDL also + * referred to as YUV. + * + * RGB colors consist of red, green, and blue channels of color that are added + * together to represent the colors we see on the screen. + * + * https://en.wikipedia.org/wiki/RGB_color_model + * + * YCbCr colors represent colors as a Y luma brightness component and red and + * blue chroma color offsets. This color representation takes advantage of the + * fact that the human eye is more sensitive to brightness than the color in + * an image. The Cb and Cr components are often compressed and have lower + * resolution than the luma component. + * + * https://en.wikipedia.org/wiki/YCbCr + * + * When the color information in YCbCr is compressed, the Y pixels are left at + * full resolution and each Cr and Cb pixel represents an average of the color + * information in a block of Y pixels. The chroma location determines where in + * that block of pixels the color information is coming from. + * + * The color range defines how much of the pixel to use when converting a + * pixel into a color on the display. When the full color range is used, the + * entire numeric range of the pixel bits is significant. When narrow color + * range is used, for historical reasons, the pixel uses only a portion of the + * numeric range to represent colors. + * + * The color primaries and white point are a definition of the colors in the + * color space relative to the standard XYZ color space. + * + * https://en.wikipedia.org/wiki/CIE_1931_color_space + * + * The transfer characteristic, or opto-electrical transfer function (OETF), + * is the way a color is converted from mathematically linear space into a + * non-linear output signals. + * + * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics + * + * The matrix coefficients are used to convert between YCbCr and RGB colors. */ #ifndef SDL_pixels_h_ @@ -41,22 +93,44 @@ extern "C" { /** * A fully opaque 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_TRANSPARENT */ #define SDL_ALPHA_OPAQUE 255 +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + /** * A fully transparent 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_OPAQUE */ #define SDL_ALPHA_TRANSPARENT 0 -/** Pixel type. */ +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, @@ -75,7 +149,11 @@ typedef enum SDL_PixelType SDL_PIXELTYPE_INDEX2 } SDL_PixelType; -/** Bitmap pixel order, high bit -> low bit. */ +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, @@ -83,7 +161,11 @@ typedef enum SDL_BitmapOrder SDL_BITMAPORDER_1234 } SDL_BitmapOrder; -/** Packed component order, high bit -> low bit. */ +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, @@ -97,7 +179,11 @@ typedef enum SDL_PackedOrder SDL_PACKEDORDER_BGRA } SDL_PackedOrder; -/** Array component order, low byte -> high byte. */ +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, @@ -109,7 +195,11 @@ typedef enum SDL_ArrayOrder SDL_ARRAYORDER_ABGR } SDL_ArrayOrder; -/** Packed component layout. */ +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, @@ -123,25 +213,172 @@ typedef enum SDL_PackedLayout SDL_PACKEDLAYOUT_1010102 } SDL_PackedLayout; +/** + * A macro for defining custom FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_YV12 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') + * ``` + * + * \param A the first character of the FourCC code. + * \param B the second character of the FourCC code. + * \param C the third character of the FourCC code. + * \param D the fourth character of the FourCC code. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) +/** + * A macro for defining custom non-FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) + * ``` + * + * \param type the type of the new format, probably a SDL_PixelType value. + * \param order the order of the new format, probably a SDL_BitmapOrder, + * SDL_PackedOrder, or SDL_ArrayOrder value. + * \param layout the layout of the new format, probably an SDL_PackedLayout + * value or zero. + * \param bits the number of bits per pixel of the new format. + * \param bytes the number of bytes per pixel of the new format. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ ((bits) << 8) | ((bytes) << 0)) -#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) -#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) -#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) -#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) -#define SDL_BITSPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU) || \ - ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF)) +/** + * A macro to retrieve the flags of an SDL_PixelFormat. + * + * This macro is generally not needed directly by an app, which should use + * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. + * + * \param format an SDL_PixelFormat to check. + * \returns the flags of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) +/** + * A macro to retrieve the type of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PixelType enumeration. + * + * \param format an SDL_PixelFormat to check. + * \returns the type of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) + +/** + * A macro to retrieve the order of an SDL_PixelFormat. + * + * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or + * SDL_ArrayOrder enumerations, depending on the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the order of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) + +/** + * A macro to retrieve the layout of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PackedLayout enumeration, or zero if a + * layout doesn't make sense for the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the layout of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) + +/** + * A macro to determine an SDL_PixelFormat's bits per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats will report zero here, as it rarely makes sense to measure + * them per-pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bits-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTESPERPIXEL + */ +#define SDL_BITSPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) + +/** + * A macro to determine an SDL_PixelFormat's bytes per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats do their best here, but many of them don't have a meaningful + * measurement of bytes per pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bytes-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BITSPERPIXEL + */ +#define SDL_BYTESPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? \ + ((((format) == SDL_PIXELFORMAT_YUY2) || \ + ((format) == SDL_PIXELFORMAT_UYVY) || \ + ((format) == SDL_PIXELFORMAT_YVYU) || \ + ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) + + +/** + * A macro to determine if an SDL_PixelFormat is an indexed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is indexed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -149,12 +386,38 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) +/** + * A macro to determine if an SDL_PixelFormat is a packed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is packed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_PACKED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) +/** + * A macro to determine if an SDL_PixelFormat is an array format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is an array, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -163,25 +426,84 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -#define SDL_ISPIXELFORMAT_ALPHA(format) \ - ((SDL_ISPIXELFORMAT_PACKED(format) && \ - ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))) - +/** + * A macro to determine if an SDL_PixelFormat is a 10-bit format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_10BIT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) +/** + * A macro to determine if an SDL_PixelFormat is a floating point format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ -#define SDL_ISPIXELFORMAT_FOURCC(format) \ +/** + * A macro to determine if an SDL_PixelFormat has an alpha channel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_ALPHA(format) \ + ((SDL_ISPIXELFORMAT_PACKED(format) && \ + ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ + (SDL_ISPIXELFORMAT_ARRAY(format) && \ + ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) + + +/** + * A macro to determine if an SDL_PixelFormat is a "FourCC" format. + * + * This covers custom and other unusual formats. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this enum, update SDL_GetPixelFormatName() */ @@ -221,7 +543,7 @@ typedef enum SDL_PackedLayout * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for * RGBA8888 on big-endian CPUs. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PixelFormat { @@ -351,59 +673,35 @@ typedef enum SDL_PixelFormat /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ - SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif } SDL_PixelFormat; -/* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 -#else -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888 -#endif - -/** - * Pixels are a representation of a color in a particular color space. - * - * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV. - * - * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen. - * https://en.wikipedia.org/wiki/RGB_color_model - * - * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component. - * https://en.wikipedia.org/wiki/YCbCr - * - * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from. - * - * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors. - * - * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space. - * https://en.wikipedia.org/wiki/CIE_1931_color_space - * - * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals. - * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics - * - * The matrix coefficients are used to convert between YCbCr and RGB colors. - */ - /** * Colorspace color type. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorType { @@ -416,7 +714,7 @@ typedef enum SDL_ColorType * Colorspace color range, as described by * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorRange { @@ -429,7 +727,7 @@ typedef enum SDL_ColorRange * Colorspace color primaries, as described by * https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorPrimaries { @@ -454,7 +752,7 @@ typedef enum SDL_ColorPrimaries * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TransferCharacteristics { @@ -484,7 +782,7 @@ typedef enum SDL_TransferCharacteristics * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MatrixCoefficients { @@ -508,7 +806,7 @@ typedef enum SDL_MatrixCoefficients /** * Colorspace chroma sample location. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ChromaLocation { @@ -520,22 +818,177 @@ typedef enum SDL_ChromaLocation /* Colorspace definition */ + +/** + * A macro for defining custom SDL_Colorspace formats. + * + * For example, defining SDL_COLORSPACE_SRGB looks like this: + * + * ```c + * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + * SDL_COLOR_RANGE_FULL, + * SDL_COLOR_PRIMARIES_BT709, + * SDL_TRANSFER_CHARACTERISTICS_SRGB, + * SDL_MATRIX_COEFFICIENTS_IDENTITY, + * SDL_CHROMA_LOCATION_NONE) + * ``` + * + * \param type the type of the new format, probably an SDL_ColorType value. + * \param range the range of the new format, probably a SDL_ColorRange value. + * \param primaries the primaries of the new format, probably an + * SDL_ColorPrimaries value. + * \param transfer the transfer characteristics of the new format, probably an + * SDL_TransferCharacteristics value. + * \param matrix the matrix coefficients of the new format, probably an + * SDL_MatrixCoefficients value. + * \param chroma the chroma sample location of the new format, probably an + * SDL_ChromaLocation value. + * \returns a format value in the style of SDL_Colorspace. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) -#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F) -#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F) -#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F) -#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) -#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) -#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F) +/** + * A macro to retrieve the type of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorType for `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) -#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) -#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) -#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) -#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) -#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) +/** + * A macro to retrieve the range of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorRange of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) + +/** + * A macro to retrieve the chroma sample location of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ChromaLocation of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) + +/** + * A macro to retrieve the primaries of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorPrimaries of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) + +/** + * A macro to retrieve the transfer characteristics of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_TransferCharacteristics of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) + +/** + * A macro to retrieve the matrix coefficients of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_MatrixCoefficients of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) + +/** + * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix + * coefficients. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT601 or BT470BG, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) + +/** + * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) + +/** + * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix + * coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT2020_NCL, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) + +/** + * A macro to determine if an SDL_Colorspace has a limited range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if limited range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) + +/** + * A macro to determine if an SDL_Colorspace has a full range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if full range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. @@ -544,7 +997,7 @@ typedef enum SDL_ChromaLocation * function, etc.), this is not an exhaustive list, but rather a * representative sample of the kinds of colorspaces supported in SDL. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_ColorPrimaries * \sa SDL_ColorRange @@ -631,7 +1084,7 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ - SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, SDL_COLOR_RANGE_FULL, SDL_COLOR_PRIMARIES_BT2020, @@ -639,15 +1092,10 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ } SDL_Colorspace; - -/* The default colorspace for RGB surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB - -/* The default colorspace for YUV surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG - /** * A structure that represents a color as RGBA components. * @@ -656,7 +1104,7 @@ typedef enum SDL_Colorspace * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Color { @@ -670,7 +1118,7 @@ typedef struct SDL_Color * The bits of this structure can be directly reinterpreted as a float-packed * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_FColor { @@ -683,7 +1131,7 @@ typedef struct SDL_FColor /** * A set of indexed colors representing a palette. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -698,7 +1146,7 @@ typedef struct SDL_Palette /** * Details about the format of a pixel. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PixelFormatDetails { @@ -729,7 +1177,7 @@ typedef struct SDL_PixelFormatDetails * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); @@ -742,16 +1190,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * \param Gmask a pointer filled in with the green mask for the format. * \param Bmask a pointer filled in with the blue mask for the format. * \param Amask a pointer filled in with the alpha mask for the format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatForMasks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); /** * Convert a bpp value and RGBA masks to an enumerated pixel format. @@ -769,7 +1217,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMasksForPixelFormat */ @@ -788,7 +1236,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); @@ -804,7 +1252,7 @@ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDet * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyPalette * \sa SDL_SetPaletteColors @@ -819,15 +1267,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); * \param colors an array of SDL_Color structures to copy into the palette. * \param firstcolor the index of the first palette entry to modify. * \param ncolors the number of entries to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); /** * Free a palette created with SDL_CreatePalette(). @@ -837,7 +1285,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette */ @@ -872,7 +1320,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB @@ -911,7 +1359,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -939,7 +1387,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -971,7 +1419,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform.h index bfdfa3a..e40f009 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,7 +51,7 @@ extern "C" { * \returns the name of the platform. If the correct platform name is not * available, returns a string beginning with the text "Unknown". * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform_defines.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform_defines.h index e7f91cf..7e9a0a9 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform_defines.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_platform_defines.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,180 +29,450 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 -#endif -#ifdef __NGAGE__ -#define SDL_PLATFORM_NGAGE 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ -#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif defined(HAVE_WINAPIFAMILY_H) && HAVE_WINAPIFAMILY_H + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT -#define SDL_PLATFORM_WINRT 1 +#error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_power.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_power.h index 1fdef78..4056ce3 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_power.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_power.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,15 @@ * # CategoryPower * * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ #include @@ -42,7 +51,7 @@ extern "C" { * * These are results returned by SDL_GetPowerInfo(). * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PowerState { @@ -80,7 +89,7 @@ typedef enum SDL_PowerState * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_process.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_process.h new file mode 100644 index 0000000..2cc7739 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_process.h @@ -0,0 +1,430 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used + * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set + * to `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value + * describing where standard error for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_properties.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_properties.h index c3a2c82..1f47d5f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_properties.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_properties.h @@ -1,6 +1,6 @@ /* - Simple DiretMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -61,14 +61,14 @@ extern "C" { /** * SDL properties ID * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PropertiesID; /** * SDL property type * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PropertyType { @@ -86,7 +86,7 @@ typedef enum SDL_PropertyType * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); @@ -100,7 +100,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyProperties */ @@ -116,14 +116,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); * * \param src the properties to copy. * \param dst the destination properties. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** * Lock a group of properties. @@ -138,16 +138,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SD * thread. * * \param props the properties to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockProperties */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** * Unlock a group of properties. @@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockProperties */ @@ -180,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); * \threadsafety This callback may fire without any locks held; if this is a * concern, the app should provide its own locking. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetPointerPropertyWithCleanup */ @@ -204,18 +204,18 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \param cleanup the function to call when this property is deleted, or NULL * if no cleanup is necessary. * \param userdata a pointer that is passed to the cleanup function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_SetPointerProperty * \sa SDL_CleanupPropertyCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); /** * Set a pointer property in a group of properties. @@ -223,12 +223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_HasProperty @@ -238,7 +238,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \sa SDL_SetPointerPropertyWithCleanup * \sa SDL_SetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); /** * Set a string property in a group of properties. @@ -249,16 +249,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID pro * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** * Set an integer property in a group of properties. @@ -266,16 +266,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumberProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** * Set a floating point property in a group of properties. @@ -283,16 +283,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetFloatProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** * Set a boolean property in a group of properties. @@ -300,31 +300,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); /** * Return whether a property exists in a group of properties. * * \param props the properties to query. * \param name the name of the property to query. - * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. + * \returns true if the property exists, or false if it doesn't. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** * Get the type of a property in a group of properties. @@ -336,7 +336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasProperty */ @@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty * \sa SDL_GetFloatProperty @@ -391,7 +391,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -413,7 +413,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -435,7 +435,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -457,27 +457,27 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty * \sa SDL_SetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); /** * Clear a property from a group of properties. * * \param props the properties to modify. * \param name the name of the property to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); /** * A callback used to enumerate all the properties in a group of properties. @@ -492,7 +492,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, c * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this * callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EnumerateProperties */ @@ -507,14 +507,14 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop * \param props the properties to query. * \param callback the function to call for each property. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** * Destroy a group of properties. @@ -528,7 +528,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID pr * locked or other threads might be setting or getting values * from these properties. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_rect.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_rect.h index ea97df9..8998de6 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_rect.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_rect.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,7 +23,7 @@ * # CategoryRect * * Some helper functions for managing rectangles and 2D points, in both - * interger and floating point versions. + * integer and floating point versions. */ #ifndef SDL_rect_h_ @@ -41,7 +41,7 @@ extern "C" { /** * The structure that defines a point (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect @@ -55,7 +55,7 @@ typedef struct SDL_Point /** * The structure that defines a point (using floating point values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat @@ -70,7 +70,7 @@ typedef struct SDL_FPoint /** * A rectangle, with the origin at the upper left (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmpty * \sa SDL_RectsEqual @@ -91,7 +91,7 @@ typedef struct SDL_Rect * A rectangle, with the origin at the upper left (using floating point * values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -121,7 +121,7 @@ typedef struct SDL_FRect * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) { @@ -146,16 +146,16 @@ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) { return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; } /** @@ -170,15 +170,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) { - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; } /** @@ -194,51 +194,51 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) { return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; + (a->w == b->w) && (a->h == b->h)) ? true : false; } /** * Determine whether two rectangles intersect. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); /** * Calculate the intersection of two rectangles. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate the union of two rectangles. @@ -247,12 +247,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate a minimal rectangle enclosing a set of points. @@ -266,12 +266,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const S * \param clip an SDL_Rect used for clipping or NULL to enclose all points. * \param result an SDL_Rect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); /** * Calculate the intersection of a rectangle and line segment. @@ -287,11 +287,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); /* SDL_FRect versions... */ @@ -311,16 +311,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Re * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) { return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && - (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; } /** @@ -335,15 +335,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) { - return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; } /** @@ -363,22 +363,22 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * \param a the first rectangle to test. * \param b the second rectangle to test. * \param epsilon the epsilon value for comparison. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualFloat */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) { return (a && b && ((a == b) || ((SDL_fabsf(a->x - b->x) <= epsilon) && (SDL_fabsf(a->y - b->y) <= epsilon) && (SDL_fabsf(a->w - b->w) <= epsilon) && (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; + ? true : false; } /** @@ -398,15 +398,15 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualEpsilon */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) { return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); } @@ -414,34 +414,34 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec /** * Determine whether two rectangles intersect with float precision. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); /** * Calculate the intersection of two rectangles with float precision. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersectionFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate the union of two rectangles with float precision. @@ -450,12 +450,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate a minimal rectangle enclosing a set of points with float @@ -470,12 +470,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, c * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); /** * Calculate the intersection of a rectangle and line segment with float @@ -492,11 +492,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_render.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_render.h index 706308c..891e994 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_render.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_render.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -40,8 +40,8 @@ * * This API is designed to accelerate simple 2D operations. You may want more * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. + * should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the + * many good 3D engines. * * These functions must be called from the main thread. See this bug for * details: https://github.com/libsdl-org/SDL/issues/986 @@ -51,10 +51,13 @@ #define SDL_render_h_ #include +#include #include #include +#include #include #include +#include #include #include @@ -66,14 +69,14 @@ extern "C" { /** * The name of the software renderer. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_SOFTWARE_RENDERER "software" /** * Vertex structure. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Vertex { @@ -85,7 +88,7 @@ typedef struct SDL_Vertex /** * The access pattern allowed for a texture. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TextureAccess { @@ -97,7 +100,7 @@ typedef enum SDL_TextureAccess /** * How the logical size is mapped to the output. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_RendererLogicalPresentation { @@ -111,15 +114,32 @@ typedef enum SDL_RendererLogicalPresentation /** * A structure representing rendering state * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Renderer SDL_Renderer; +#ifndef SDL_INTERNAL + /** * An efficient driver-specific representation of pixel data * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ @@ -135,7 +155,9 @@ typedef struct SDL_Texture SDL_Texture; * * \returns the number of built in render drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_GetRenderDriver @@ -158,7 +180,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * \returns the name of the rendering driver at the requested index, or NULL * if an invalid index was specified. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumRenderDrivers */ @@ -174,36 +198,43 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * SDL_CreateWindow()). * \param window a pointer filled with the window, or NULL on error. * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); /** * Create a 2D rendering context for a window. * * If you want a specific renderer, you can specify its name here. A list of - * available renderers can be obtained by calling SDL_GetRenderDriver multiple - * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't - * need a specific renderer, specify NULL and SDL will attempt to choose the - * best option for you, based on what is available on the user's system. + * available renderers can be obtained by calling SDL_GetRenderDriver() + * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you + * don't need a specific renderer, specify NULL and SDL will attempt to choose + * the best option for you, based on what is available on the user's system. + * + * If `name` is a comma-separated list, SDL will try each name, in the order + * listed, until one succeeds or all of them fail. * * By default the rendering size matches the window size in pixels, but you * can call SDL_SetRenderLogicalPresentation() to change the content size and * scaling options. * * \param window the window where rendering is displayed. - * \param name the name of the rendering driver to initialize, or NULL to - * initialize the first one supporting the requested flags. + * \param name the name of the rendering driver to initialize, or NULL to let + * SDL choose one. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRendererWithProperties * \sa SDL_CreateSoftwareRenderer @@ -225,7 +256,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * displayed, required if this isn't a software renderer using a surface * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering * is displayed, if you want a software renderer without a window - * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace + * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace * value describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and @@ -255,7 +286,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateRenderer @@ -290,7 +323,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRenderer */ @@ -303,7 +338,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surfac * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); @@ -314,7 +351,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); @@ -325,7 +364,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende * \returns the name of the selected renderer, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateRendererWithProperties @@ -348,21 +389,21 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN, * representing the available texture formats for this renderer. - * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with * HDR enabled. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is * automatically multiplied into the color scale. This property can change - * dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range * that can be displayed, in terms of the SDR white point. When HDR is not * enabled, this will be 1.0. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * * With the direct3d renderer: * @@ -403,11 +444,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * swapchain images, or potential frames in flight, used by the Vulkan * renderer * + * With the gpu renderer: + * + * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with + * the renderer + * * \param renderer the rendering context. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); @@ -434,6 +482,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende #define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count" +#define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device" /** * Get the output size in pixels of a rendering context. @@ -444,14 +493,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \param renderer the rendering context. * \param w a pointer filled in with the width in pixels. * \param h a pointer filled in with the height in pixels. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Get the current output size in pixels of a rendering context. @@ -464,28 +515,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *rende * \param renderer the rendering context. * \param w a pointer filled in with the current width. * \param h a pointer filled in with the current height. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Create a texture for a rendering context. * + * The contents of a texture when first created are not defined. + * * \param renderer the rendering context. * \param format one of the enumerated values in SDL_PixelFormat. * \param access one of the enumerated values in SDL_TextureAccess. * \param w the width of the texture in pixels. * \param h the height of the texture in pixels. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTextureFromSurface * \sa SDL_CreateTextureWithProperties @@ -513,7 +569,9 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureWithProperties @@ -526,7 +584,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * These are the supported properties: * - * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for @@ -617,11 +675,12 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * \param renderer the rendering context. * \param props the properties to use. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateTexture @@ -661,7 +720,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * The following read-only properties are provided by SDL: * - * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing + * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing * the texture colorspace. * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in * SDL_PixelFormat. @@ -701,14 +760,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * With the vulkan renderer: * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_POINTER`: the VkImage associated with - * the texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_U_POINTER`: the VkImage associated with - * the U plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_V_POINTER`: the VkImage associated with - * the V plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_UV_POINTER`: the VkImage associated with - * the UV plane of a NV12/NV21 texture + * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the + * texture * * With the opengl renderer: * @@ -740,16 +793,13 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc) * - * With the vulkan renderer: - * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the - * texture - * * \param texture the texture to query. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); @@ -789,7 +839,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Textur * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture); @@ -801,12 +851,14 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This * argument can be NULL if you don't need this information. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); /** * Set an additional color value multiplied into render copy operations. @@ -818,22 +870,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, fl * `srcC = srcC * (color / 255)` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); /** @@ -846,22 +900,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture * `srcC = srcC * color` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); /** @@ -871,16 +927,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *te * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); /** * Get the additional color value multiplied into render copy operations. @@ -889,16 +947,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); /** * Set an additional alpha value multiplied into render copy operations. @@ -909,20 +969,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *te * `srcA = srcA * (alpha / 255)` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); /** * Set an additional alpha value multiplied into render copy operations. @@ -933,83 +995,93 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture * `srcA = srcA * alpha` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); /** * Set the blend mode for a texture, used by SDL_RenderTexture(). * * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. + * and this function returns false. * * \param texture the texture to update. * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); /** * Get the blend mode used for texture copy operations. * * \param texture the texture to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); /** * Set the scale mode used for texture scale operations. @@ -1020,28 +1092,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *textur * * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); /** * Get the scale mode used for texture scale operations. * * \param texture the texture to query. * \param scaleMode a pointer filled in with the current scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); /** * Update the given texture rectangle with new pixel data. @@ -1063,17 +1139,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *textur * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding * between lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture * \sa SDL_UpdateNVTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); /** * Update a rectangle within a planar YV12 or IYUV texture with new pixel @@ -1095,15 +1173,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, con * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateNVTexture * \sa SDL_UpdateTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, @@ -1125,15 +1205,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \param UVplane the raw pixel data for the UV plane. * \param UVpitch the number of bytes between rows of pixel data for the UV * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch); @@ -1157,16 +1239,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the * pitch is the length of one row in bytes. - * \returns SDL_TRUE on success or SDL_FALSE if the texture is not valid or - * was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. + * \returns true on success or false if the texture is not valid or was not + * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTextureToSurface * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch); @@ -1192,17 +1276,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** * Unlock a texture, uploading the changes to video memory, if needed. @@ -1217,7 +1303,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *textu * * \param texture a texture locked by SDL_LockTexture(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture */ @@ -1234,14 +1322,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderTarget */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** * Get the current render target. @@ -1252,7 +1342,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderTarget */ @@ -1261,13 +1353,23 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend /** * Set a device independent resolution and presentation mode for rendering. * - * This function sets the width and height of the logical rendering output. A - * render target is created at the specified size and used for rendering and - * then copied to the output during presentation. + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the window is always the requested dimensions, + * scaling to the actual window resolution as necessary. + * + * This can be useful for games that expect a fixed size, but would like to + * scale the output to whatever is available, regardless of how a user resizes + * a window, or if the display is high DPI. * * You can disable logical coordinates by setting the mode to * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel - * resolution of the output window. + * resolution of the output window; it is safe to toggle logical presentation + * during the rendering of a frame: perhaps most of the rendering is done to + * specific dimensions but to make fonts look sharp, the app turns off logical + * presentation while drawing text. + * + * Letterboxing will only happen if logical presentation is enabled during + * SDL_RenderPresent; be sure to reenable it first if you were using it. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). @@ -1276,17 +1378,18 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \param w the width of the logical resolution. * \param h the height of the logical resolution. * \param mode the presentation mode used. - * \param scale_mode the scale mode used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertEventToRenderCoordinates * \sa SDL_GetRenderLogicalPresentation * \sa SDL_GetRenderLogicalPresentationRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); /** * Get device independent resolution and presentation mode for rendering. @@ -1297,16 +1400,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param w an int to be filled with the width. * \param h an int to be filled with the height. - * \param mode a pointer filled in with the presentation mode. - * \param scale_mode a pointer filled in with the scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); /** * Get the final presentation rectangle for rendering. @@ -1319,36 +1423,54 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param rect a pointer filled in with the final presentation rectangle, may * be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); /** * Get a point in render coordinates when given a point in window coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param window_x the x coordinate in window coordinates. * \param window_y the y coordinate in window coordinates. * \param x a pointer filled with the x coordinate in render coordinates. * \param y a pointer filled with the y coordinate in render coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); /** * Get a point in window coordinates when given a point in render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param x the x coordinate in render coordinates. * \param y the y coordinate in render coordinates. @@ -1356,65 +1478,95 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Rendere * coordinates. * \param window_y a pointer filled with the y coordinate in window * coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); /** * Convert the coordinates in an event to render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * Various event types are converted with this function: mouse, touch, pen, + * etc. + * * Touch coordinates are converted from normalized coordinates in the window * to non-normalized rendering coordinates. * - * Once converted, the coordinates may be outside the rendering area. + * Relative mouse coordinates (xrel and yrel event fields) are _also_ + * converted. Applications that do not want these fields converted should use + * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of + * converting the entire event structure. + * + * Once converted, coordinates may be outside the rendering area. * * \param renderer the rendering context. * \param event the event to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderCoordinatesFromWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); /** * Set the drawing area for rendering on the current target. * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL * to set the viewport to the entire target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_RenderViewportSet */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the drawing area for the current target. * * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current drawing area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderViewportSet * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); /** * Return whether an explicit rectangle was set as the viewport. @@ -1424,15 +1576,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *rendere * viewport is always reset when changing rendering targets. * * \param renderer the rendering context. - * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target). + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); /** * Get the safe area for rendering within the current viewport. @@ -1447,12 +1601,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect a pointer filled in with the area that is safe for interactive * content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); /** * Set the clip rectangle for rendering on the specified target. @@ -1460,15 +1616,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the clip area, relative to * the viewport, or NULL to disable clipping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_RenderClipEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the clip rectangle for the current target. @@ -1476,29 +1634,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current clipping area * or an empty rectangle if clipping is disabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderClipEnabled * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); /** * Get whether clipping is enabled on the given renderer. * * \param renderer the rendering context. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. + * \returns true if clipping is enabled or false if not; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); /** * Set the drawing scale for rendering on the current target. @@ -1514,14 +1676,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * \param renderer the rendering context. * \param scaleX the horizontal scaling factor. * \param scaleY the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); /** * Get the drawing scale for the current target. @@ -1529,14 +1693,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, * \param renderer the rendering context. * \param scaleX a pointer filled in with the horizontal scaling factor. * \param scaleY a pointer filled in with the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); /** * Set the color used for drawing operations. @@ -1551,15 +1717,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to * specify how the alpha channel is used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColor * \sa SDL_SetRenderDrawColorFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Set the color used for drawing operations (Rect, Line and Clear). @@ -1574,15 +1742,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *render * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is * used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1596,15 +1766,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *r * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1618,15 +1790,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *render * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColorFloat * \sa SDL_GetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); /** * Set the color scale used for render operations. @@ -1641,28 +1815,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *r * * \param renderer the rendering context. * \param scale the color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); /** * Get the color scale used for render operations. * * \param renderer the rendering context. * \param scale a pointer filled in with the current color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); /** * Set the blend mode used for drawing operations (Fill and Line). @@ -1671,28 +1849,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *rende * * \param renderer the rendering context. * \param blendMode the SDL_BlendMode to use for blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); /** * Get the blend mode used for drawing operations. * * \param renderer the rendering context. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); /** * Clear the current rendering target with the drawing color. @@ -1703,14 +1885,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *re * SDL_SetRenderDrawColor() when needed. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. @@ -1718,14 +1902,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \param renderer the renderer which should draw a point. * \param x the x coordinate of the point. * \param y the y coordinate of the point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); /** * Draw multiple points on the current rendering target at subpixel precision. @@ -1733,14 +1919,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, flo * \param renderer the renderer which should draw multiple points. * \param points the points to draw. * \param count the number of points to draw. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a line on the current rendering target at subpixel precision. @@ -1750,14 +1938,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, co * \param y1 the y coordinate of the start point. * \param x2 the x coordinate of the end point. * \param y2 the y coordinate of the end point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLines */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); /** * Draw a series of connected lines on the current rendering target at @@ -1766,14 +1956,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, floa * \param renderer the renderer which should draw multiple lines. * \param points the points along the lines. * \param count the number of points, drawing count-1 lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLine */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a rectangle on the current rendering target at subpixel precision. @@ -1781,14 +1973,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, con * \param renderer the renderer which should draw a rectangle. * \param rect a pointer to the destination rectangle, or NULL to outline the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Draw some number of rectangles on the current rendering target at subpixel @@ -1797,14 +1991,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, cons * \param renderer the renderer which should draw multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Fill a rectangle on the current rendering target with the drawing color at @@ -1813,14 +2009,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, con * \param renderer the renderer which should fill a rectangle. * \param rect a pointer to the destination rectangle, or NULL for the entire * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Fill some number of rectangles on the current rendering target with the @@ -1829,14 +2027,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, * \param renderer the renderer which should fill multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Copy a portion of the texture to the current rendering target at subpixel @@ -1848,15 +2048,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, * texture. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTextureRotated * \sa SDL_RenderTextureTiled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); /** * Copy a portion of the source texture to the current rendering target, with @@ -1875,17 +2077,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, S * around dstrect.w/2, dstrect.h/2). * \param flip an SDL_FlipMode value stating which flipping actions should be * performed on the texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, - const double angle, const SDL_FPoint *center, - const SDL_FlipMode flip); + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); + +/** + * Copy a portion of the source texture to the current rendering target, with + * affine transform, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param origin a pointer to a point indicating where the top-left corner of + * srcrect should be mapped to, or NULL for the rendering + * target's origin. + * \param right a pointer to a point indicating where the top-right corner of + * srcrect should be mapped to, or NULL for the rendering + * target's top-right corner. + * \param down a pointer to a point indicating where the bottom-left corner of + * srcrect should be mapped to, or NULL for the rendering target's + * bottom-left corner. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FPoint *origin, + const SDL_FPoint *right, const SDL_FPoint *down); /** * Tile a portion of the texture to the current rendering target at subpixel @@ -1903,14 +2137,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *rend * 64x64 tiles. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); /** * Perform a scaled copy using the 9-grid algorithm to the current rendering @@ -1935,14 +2171,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *render * corner of `dstrect`, or 0.0f for an unscaled copy. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); /** * Render a list of triangles, optionally using a texture and indices into the @@ -1957,14 +2195,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *render * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices number of indices. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometryRaw */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices); @@ -1987,14 +2227,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * if NULL all vertices will be rendered in sequential order. * \param num_indices number of indices. * \param size_indices index size: 1 (byte), 2 (short), 4 (int). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometry */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, @@ -2017,7 +2259,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *rendere * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); @@ -2041,18 +2285,20 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * pixel. * * Please note, that in case of rendering to a texture - there is **no need** - * to call `SDL_RenderPresent` after drawing needed objects to a texture, you - * are only required to change back the rendering target to default via - * `SDL_SetRenderTarget(renderer, NULL)` afterwards, as textures by themselves - * do not have a concept of backbuffers. + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \threadsafety You may only call this function on the main thread. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_RenderClear @@ -2067,7 +2313,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \sa SDL_SetRenderDrawBlendMode * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); /** * Destroy the specified texture. @@ -2077,7 +2323,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureFromSurface @@ -2092,7 +2340,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer */ @@ -2122,12 +2372,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * be prepared to make changes if specific state needs to be protected. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); /** * Get the CAMetalLayer associated with the given Metal renderer. @@ -2139,7 +2391,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalCommandEncoder */ @@ -2160,7 +2414,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalLayer */ @@ -2187,15 +2443,15 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not * needed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is **NOT** safe to call this function from two threads at * once. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); /** * Toggle VSync of the given renderer. @@ -2204,21 +2460,23 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer * * The `vsync` parameter can be 1 to synchronize present with every vertical * refresh, 2 to synchronize present with every second vertical refresh, etc., - * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), - * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is - * supported by every driver, so you should check the return value to see - * whether the requested setting is supported. + * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or + * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by + * every driver, so you should check the return value to see whether the + * requested setting is supported. * * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); #define SDL_RENDERER_VSYNC_DISABLED 0 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1) @@ -2229,14 +2487,96 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, * \param renderer the renderer to toggle. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetRenderVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); + +/** + * The size, in pixels, of a single SDL_RenderDebugText() character. + * + * The font is monospaced and square, so this applies to all characters. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + */ +#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8 + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a string of text to an SDL_Renderer. Note that + * this is a convenience function for debugging, with severe limitations, and + * not intended to be used for production apps and games. + * + * Among these limitations: + * + * - It accepts UTF-8 strings, but will only renders ASCII characters. + * - It has a single, tiny size (8x8 pixels). One can use logical presentation + * or scaling to adjust it, but it will be blurry. + * - It uses a simple, hardcoded bitmap font. It does not allow different font + * selections and it does not support truetype, for proper scaling. + * - It does no word-wrapping and does not treat newline characters as a line + * break. If the text goes out of the window, it's gone. + * + * For serious text rendering, there are several good options, such as + * SDL_ttf, stb_truetype, or other external libraries. + * + * On first use, this will create an internal texture for rendering glyphs. + * This texture will live until the renderer is destroyed. + * + * The text is drawn in the color specified by SDL_SetRenderDrawColor(). + * + * \param renderer the renderer which should draw a line of text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param str the string to render. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugTextFormat + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str); + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a printf()-style format string to a renderer. + * Note that this is a convinence function for debugging, with severe + * limitations, and is not intended to be used for production apps and games. + * + * For the full list of limitations and other useful information, see + * SDL_RenderDebugText. + * + * \param renderer the renderer which should draw the text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param fmt the format string to draw. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_revision.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_revision.h index f78e5d9..18f7c4d 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_revision.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_revision.h @@ -1,22 +1,22 @@ /* - Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga - 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. + 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: + 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. + 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. */ /* WIKI CATEGORY: Version */ @@ -48,9 +48,9 @@ */ #define SDL_REVISION "Some arbitrary string decided at SDL build time" #elif defined(SDL_VENDOR_INFO) -#define SDL_REVISION SDL_VENDOR_INFO +#define SDL_REVISION "release-3.2.0-0-g535d80bad (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "" +#define SDL_REVISION "release-3.2.0-0-g535d80bad" #endif #endif /* SDL_revision_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_scancode.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_scancode.h index ccf8bb5..9650a6c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_scancode.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_scancode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryScancode * * Defines keyboard scancodes. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_scancode_h_ @@ -42,7 +47,7 @@ * The values in this enumeration are based on the USB usage page standard: * https://usb.org/sites/default/files/hut1_5.pdf * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_Scancode { @@ -417,8 +422,8 @@ typedef enum SDL_Scancode SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_sensor.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_sensor.h index 3ae4856..b220f05 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_sensor.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_sensor.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategorySensor * * SDL sensor management. + * + * These APIs grant access to gyros and accelerometers on various platforms. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ @@ -41,14 +47,10 @@ extern "C" { #endif /** - * SDL_sensor.h + * The opaque structure used to identify an opened SDL sensor. * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system - * for sensors, and load appropriate drivers. + * \since This struct is available since SDL 3.2.0. */ - -struct SDL_Sensor; typedef struct SDL_Sensor SDL_Sensor; /** @@ -57,7 +59,7 @@ typedef struct SDL_Sensor SDL_Sensor; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SensorID; @@ -69,7 +71,7 @@ typedef Uint32 SDL_SensorID; * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the * earth, which is a positive Y value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_STANDARD_GRAVITY 9.80665f @@ -123,7 +125,7 @@ typedef Uint32 SDL_SensorID; * * The gyroscope axis data is not changed when the device is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayOrientation */ @@ -151,7 +153,7 @@ typedef enum SDL_SensorType * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); @@ -163,7 +165,7 @@ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); * \param instance_id the sensor instance ID. * \returns the sensor name, or NULL if `instance_id` is not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id); @@ -176,7 +178,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID ins * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is * not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID instance_id); @@ -189,7 +191,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID i * \returns the sensor platform dependent type, or -1 if `instance_id` is not * valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); @@ -200,7 +202,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id); @@ -211,7 +213,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); @@ -222,7 +224,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instan * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); @@ -233,7 +235,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor * \returns the sensor name or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); @@ -244,7 +246,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor); @@ -254,7 +256,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor) * \param sensor the SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor); @@ -265,7 +267,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor) * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); @@ -277,19 +279,19 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); * \param sensor the SDL_Sensor object to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** * Close a sensor previously opened with SDL_OpenSensor(). * * \param sensor the SDL_Sensor object to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); @@ -302,7 +304,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); * This needs to be called from the thread that initialized the sensor * subsystem. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateSensors(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_stdinc.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_stdinc.h index 5539f2a..4e15a3c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_stdinc.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_stdinc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,25 @@ /** * # CategoryStdinc * - * This is a general header that includes C language support. It implements a - * subset of the C runtime: these should all behave the same way as their C - * runtime equivalents, but with an SDL_ prefix. + * SDL provides its own implementation of some of the most important C runtime + * functions. + * + * Using these functions allows an app to have access to common C + * functionality without depending on a specific C runtime (or a C runtime at + * all). More importantly, the SDL implementations work identically across + * platforms, so apps can avoid surprises like snprintf() behaving differently + * between Windows and Linux builds, or itoa() only existing on some + * platforms. + * + * For many of the most common functions, like SDL_memcpy, SDL might just call + * through to the usual C runtime behind the scenes, if it makes sense to do + * so (if it's faster and always available/reliable on a given platform), + * reducing library size and offering the most optimized option. + * + * SDL also offers other C-runtime-adjacent functionality in this header that + * either isn't, strictly speaking, part of any C runtime standards, like + * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better + * options, like SDL_strlcpy(), which functions as a safer form of strcpy(). */ #ifndef SDL_stdinc_h_ @@ -32,17 +48,34 @@ #include -#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -#include -#endif #include -#ifndef __cplusplus -#include -#endif #include #include #include +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H) +#if __has_include() +#define SDL_INCLUDE_STDBOOL_H +#endif +#endif +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + #ifndef SDL_DISABLE_ALLOCA # ifndef alloca # ifdef HAVE_ALLOCA_H @@ -74,31 +107,120 @@ void *alloca(size_t); # endif #endif -#ifdef SIZE_MAX + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Don't let SDL use "long long" C types. + * + * SDL will define this if it believes the compiler doesn't understand the + * "long long" syntax for C datatypes. This can happen on older compilers. + * + * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it + * is safe to define this yourself to build against the SDL headers. + * + * If this is defined, it will remove access to some C runtime support + * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype + * explicitly. The rest of SDL will still be available. + * + * SDL's own source code cannot be built with a compiler that has this + * defined, for various technical reasons. + */ +#define SDL_NOLONGLONG 1 + +#elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */ +# define SDL_NOLONGLONG 1 +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The largest value that a `size_t` can hold for the target platform. + * + * `size_t` is generally the same size as a pointer in modern times, but this + * can get weird on very old and very esoteric machines. For example, on a + * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment + * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with + * the offset into an individual segment. + * + * In modern times, it's generally expected to cover an entire linear address + * space. But be careful! + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SIZE_MAX SIZE_MAX + +#elif defined(SIZE_MAX) # define SDL_SIZE_MAX SIZE_MAX #else # define SDL_SIZE_MAX ((size_t) -1) #endif +#ifndef SDL_COMPILE_TIME_ASSERT +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + /** - * Check if the compiler supports a given builtin. - * Supported by virtually all clang versions and recent gcc. Use this - * instead of checking the clang version if possible. + * A compile-time assertion. + * + * This can check constant values _known to the compiler at build time_ for + * correctness, and end the compile with the error if they fail. + * + * Often times these are used to verify basic truths, like the size of a + * datatype is what is expected: + * + * ```c + * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); + * ``` + * + * The `name` parameter must be a valid C symbol, and must be unique across + * all compile-time asserts in the same compilation unit (one run of the + * compiler), or the build might fail with cryptic errors on some targets. + * This is used with a C language trick that works on older compilers that + * don't support better assertion techniques. + * + * If you need an assertion that operates at runtime, on variable data, you + * should try SDL_assert instead. + * + * \param name a unique identifier for this assertion. + * \param x the value to test. Must be a boolean value. + * + * \threadsafety This macro doesn't generate any code to run. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_assert */ -#ifdef __has_builtin -#define SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define SDL_HAS_BUILTIN(x) 0 +#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x) +#elif defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] #endif /** - * The number of elements in an array. + * The number of elements in a static array. + * + * This will compile but return incorrect results for a pointer to an array; + * it has to be an array the compiler knows the size of. * * This macro looks like it double-evaluates the argument, but it does so * inside of `sizeof`, so there are no side-effects here, as expressions do * not actually run any code in these cases. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) @@ -111,7 +233,9 @@ void *alloca(size_t); * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * ``` * - * \since This macro is available since SDL 3.0.0. + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -122,7 +246,76 @@ void *alloca(size_t); * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). */ /* @{ */ -#ifdef __cplusplus + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) #define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) #define SDL_static_cast(type, expression) static_cast(expression) #define SDL_const_cast(type, expression) const_cast(expression) @@ -131,9 +324,23 @@ void *alloca(size_t); #define SDL_static_cast(type, expression) ((type)(expression)) #define SDL_const_cast(type, expression) ((type)(expression)) #endif + /* @} *//* Cast operators */ -/* Define a four character code as a Uint32 */ +/** + * Define a four character code as a Uint32. + * + * \param A the first ASCII character. + * \param B the second ASCII character. + * \param C the third ASCII character. + * \param D the fourth ASCII character. + * \returns the four characters converted into a Uint32, one character + * per-byte. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FOURCC(A, B, C, D) \ ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ @@ -149,7 +356,7 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -162,63 +369,49 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ -#elif defined(INT64_C) +#else /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +#ifndef SDL_SINT64_C +#if defined(INT64_C) #define SDL_SINT64_C(c) INT64_C(c) -#define SDL_UINT64_C(c) UINT64_C(c) #elif defined(_MSC_VER) #define SDL_SINT64_C(c) c ## i64 -#define SDL_UINT64_C(c) c ## ui64 #elif defined(__LP64__) || defined(_LP64) #define SDL_SINT64_C(c) c ## L -#define SDL_UINT64_C(c) c ## UL #else #define SDL_SINT64_C(c) c ## LL +#endif +#endif /* !SDL_SINT64_C */ + +#ifndef SDL_UINT64_C +#if defined(UINT64_C) +#define SDL_UINT64_C(c) UINT64_C(c) +#elif defined(_MSC_VER) +#define SDL_UINT64_C(c) c ## ui64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_UINT64_C(c) c ## UL +#else #define SDL_UINT64_C(c) c ## ULL #endif +#endif /* !SDL_UINT64_C */ + +#endif /* !SDL_WIKI_DOCUMENTATION_SECTION */ /** * \name Basic data types */ /* @{ */ -/** - * A boolean false. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_FALSE false - -/** - * A boolean true. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_TRUE true - -/** - * A boolean type: true or false. - * - * \since This datatype is available since SDL 3.0.0. - * - * \sa SDL_TRUE - * \sa SDL_FALSE - */ -typedef bool SDL_bool; - /** * A signed 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ @@ -227,7 +420,7 @@ typedef int8_t Sint8; /** * An unsigned 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ @@ -236,7 +429,7 @@ typedef uint8_t Uint8; /** * A signed 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ @@ -245,7 +438,7 @@ typedef int16_t Sint16; /** * An unsigned 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ @@ -254,7 +447,7 @@ typedef uint16_t Uint16; /** * A signed 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ @@ -263,7 +456,7 @@ typedef int32_t Sint32; /** * An unsigned 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ @@ -272,7 +465,7 @@ typedef uint32_t Uint32; /** * A signed 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ @@ -283,7 +476,7 @@ typedef int64_t Sint64; /** * An unsigned 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -299,7 +492,7 @@ typedef uint64_t Uint64; * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with * SDL_TimeToWindows() and SDL_TimeFromWindows(). * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_MAX_SINT64 * \sa SDL_MIN_SINT64 @@ -325,40 +518,217 @@ typedef Sint64 SDL_Time; * Equals by default to platform-defined `FLT_EPSILON`, or * `1.1920928955078125e-07F` if that's not available. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ #endif /* @} *//* Floating-point constants */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A printf-formatting string for an Sint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs64 "lld" + +/** + * A printf-formatting string for a Uint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu64 "llu" + +/** + * A printf-formatting string for a Uint64 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx64 "llx" + +/** + * A printf-formatting string for a Uint64 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX64 "llX" + +/** + * A printf-formatting string for an Sint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs32 "d" + +/** + * A printf-formatting string for a Uint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu32 "u" + +/** + * A printf-formatting string for a Uint32 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx32 "x" + +/** + * A printf-formatting string for a Uint32 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX32 "X" + +/** + * A printf-formatting string prefix for a `long long` value. + * + * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu, + * SDL_PRILLx, or SDL_PRILLX instead. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILL_PREFIX "ll" + +/** + * A printf-formatting string for a `long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLd SDL_PRILL_PREFIX "d" + +/** + * A printf-formatting string for a `unsigned long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLu SDL_PRILL_PREFIX "u" + +/** + * A printf-formatting string for an `unsigned long long` value as lower-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLx SDL_PRILL_PREFIX "x" + +/** + * A printf-formatting string for an `unsigned long long` value as upper-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* SDL_WIKI_DOCUMENTATION_SECTION */ + /* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. + * should define these but this is not true all platforms. * (for example win32) */ #ifndef SDL_PRIs64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIs64 "I64d" -#elif defined(PRIs64) -#define SDL_PRIs64 PRIs64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(PRId64) +#define SDL_PRIs64 PRId64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIs64 "ld" #else #define SDL_PRIs64 "lld" #endif #endif #ifndef SDL_PRIu64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIu64 "I64u" #elif defined(PRIu64) #define SDL_PRIu64 PRIu64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIu64 "lu" #else #define SDL_PRIu64 "llu" #endif #endif #ifndef SDL_PRIx64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIx64 "I64x" #elif defined(PRIx64) #define SDL_PRIx64 PRIx64 @@ -369,7 +739,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIX64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIX64 "I64X" #elif defined(PRIX64) #define SDL_PRIX64 PRIX64 @@ -407,9 +777,318 @@ typedef Sint64 SDL_Time; #define SDL_PRIX32 "X" #endif #endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#endif +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Macro that annotates function params with input buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + * ``` + * + * This notes that `src` should be `len` bytes in size and is only read by the + * function. The compiler or other analysis tools can warn when this doesn't + * appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) + +/** + * Macro that annotates function params with input/output string buffer size. + * + * If we were to annotate `strlcat`: + * + * ```c + * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + * ``` + * + * This notes that `dst` is a null-terminated C string, should be `maxlen` + * bytes in size, and is both read from and written to by the function. The + * compiler or other analysis tools can warn when this doesn't appear to be + * the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) + +/** + * Macro that annotates function params with output string buffer size. + * + * If we were to annotate `snprintf`: + * + * ```c + * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...); + * ``` + * + * This notes that `text` is a null-terminated C string, should be `maxlen` + * bytes in size, and is only written to by the function. The compiler or + * other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `wcsncpy`: + * + * ```c + * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` wchar_t in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for + * bytes. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_CAP(x) _Out_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) + +/** + * Macro that annotates function params with output buffer string size. + * + * If we were to annotate `strcpy`: + * + * ```c + * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and a zero-terminated string is written to it by the function. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +/** + * Macro that annotates function params as printf-style format strings. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a printf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ + +/** + * Macro that annotates function params as scanf-style format strings. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a scanf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ + +/** + * Macro that annotates a vararg function that operates like printf. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like printf. + * + * If we were to annotate `vfprintf`: + * + * ```c + * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like scanf. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by `...`. The compiler or other analysis tools can warn when this + * doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like scanf. + * + * If we were to annotate `vfscanf`: + * + * ```c + * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by a va_list. The compiler or other analysis tools can warn when + * this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like wprintf. + * + * If we were to annotate `fwprintf`: + * + * ```c + * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ + +/** + * Macro that annotates a va_list function that operates like wprintf. + * + * If we were to annotate `vfwprintf`: + * + * ```c + * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + +#elif defined(SDL_DISABLE_ANALYZE_MACROS) #define SDL_IN_BYTECAP(x) #define SDL_INOUT_Z_CAP(x) #define SDL_OUT_Z_CAP(x) @@ -423,7 +1102,7 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -447,53 +1126,45 @@ typedef Sint64 SDL_Time; #define SDL_PRINTF_FORMAT_STRING #define SDL_SCANF_FORMAT_STRING #endif -#ifdef __GNUC__ +#if defined(__GNUC__) || defined(__clang__) #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(bool, sizeof(SDL_bool) == 1); -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +#endif +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ /** \endcond */ @@ -523,7 +1194,96 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); extern "C" { #endif -#ifndef SDL_DISABLE_ALLOCA +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Allocate memory on the stack (maybe). + * + * If SDL knows how to access alloca() on the current platform, it will use it + * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to + * heap-allocate memory. + * + * Since this might not be stack memory at all, it's important that you check + * the returned pointer for NULL, and that you call SDL_stack_free on the + * memory when done with it. Since this might be stack memory, it's important + * that you don't allocate large amounts of it, or allocate in a loop without + * returning from the function, so the stack doesn't overflow. + * + * \param type the datatype of the memory to allocate. + * \param count the number of `type` objects to allocate. + * \returns newly-allocated memory, or NULL on failure. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_free + */ +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ +#define SDL_stack_free(data) +#elif !defined(SDL_DISABLE_ALLOCA) #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) #define SDL_stack_free(data) #else @@ -531,14 +1291,184 @@ extern "C" { #define SDL_stack_free(data) SDL_free(data) #endif +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If you want to allocate memory aligned to a specific alignment, consider + * using SDL_aligned_alloc(). + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void (SDLCALL *SDL_free_func)(void *mem); /** @@ -556,7 +1486,7 @@ typedef void (SDLCALL *SDL_free_func)(void *mem); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, @@ -575,7 +1505,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func * unlikely event of a background thread calling * SDL_SetMemoryFunctions simultaneously. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions @@ -599,42 +1529,42 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \param calloc_func custom calloc function. * \param realloc_func custom realloc function. * \param free_func custom free function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but one * should not replace the memory functions once any allocations * are made! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_calloc_func calloc_func, SDL_realloc_func realloc_func, SDL_free_func free_func); /** - * Allocate memory aligned to a specific value. - * - * If `alignment` is less than the size of `void *`, then it will be increased - * to match that. - * - * The returned memory address will be a multiple of the alignment value, and - * the amount of memory allocated will be a multiple of the alignment value. + * Allocate memory aligned to a specific alignment. * * The memory returned by this function must be freed with SDL_aligned_free(), - * and _not_ SDL_free. + * _not_ SDL_free(). * - * \param alignment the alignment requested. + * If `alignment` is less than the size of `void *`, it will be increased to + * match that. + * + * The returned memory address will be a multiple of the alignment value, and + * the size of the memory allocated will be a multiple of the alignment value. + * + * \param alignment the alignment of the memory. * \param size the size to allocate. - * \returns a pointer to the aligned memory. + * \returns a pointer to the aligned memory, or NULL if allocation failed. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_free */ @@ -646,11 +1576,13 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment * The pointer is no longer valid after this call and cannot be dereferenced * anymore. * - * \param mem a pointer previously returned by SDL_aligned_alloc. + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc */ @@ -659,31 +1591,552 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); /** * Get the number of outstanding (unfreed) allocations. * - * \returns the number of allocations. + * \returns the number of allocations or -1 if allocation counting is + * disabled. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); -extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); -extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); +/** + * Compute the absolute value of `x`. + * + * \param x an integer value. + * \returns the absolute value of x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); -/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ +/** + * Return the lesser of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) + +/** + * Return the greater of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `>` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) + +/** + * Return a value clamped to a range. + * + * If `x` is outside the range a values between `a` and `b`, the returned + * value will be `a` or `b` as appropriate. Otherwise, `x` is returned. + * + * This macro will produce incorrect results if `b` is less than `a`. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` and `>` operators. However, it double-evaluates all its parameters, so + * do not use expressions with side-effects here. + * + * \param x the value to compare. + * \param a the low end value. + * \param b the high end value. + * \returns x, clamped between a and b. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) /** @@ -697,7 +2150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); @@ -712,7 +2165,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); @@ -727,7 +2180,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); @@ -742,7 +2195,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); @@ -757,7 +2210,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); @@ -772,7 +2225,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); @@ -787,7 +2240,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isgraph * \sa SDL_isalnum @@ -812,7 +2265,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); @@ -827,7 +2280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); @@ -842,7 +2295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); @@ -861,7 +2314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); @@ -880,7 +2333,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isprint */ @@ -900,7 +2353,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); @@ -918,13 +2371,96 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); +/** + * Calculate a CRC-16 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-16 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-16 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); + +/** + * Calculate a CRC-32 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-32 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-32 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); +/** + * Calculate a 32-bit MurmurHash3 value for a block of data. + * + * https://en.wikipedia.org/wiki/MurmurHash + * + * A seed may be specified, which changes the final results consistently, but + * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous + * result from this function back into itself as the next seed value to + * calculate a hash in chunks; it won't produce the same hash as it would if + * the same data was provided in a single call. + * + * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not + * cryptographically secure, so it shouldn't be used for hashing top-secret + * data. + * + * \param data the data to be hashed. + * \param len the size of data, in bytes. + * \param seed a value that alters the final hash value. + * \returns a Murmur3 32-bit hash value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); + +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memmove + */ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memcpy */ @@ -935,10 +2471,52 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD #define SDL_memcpy memcpy #endif + +/** + * A macro to copy memory between objects, with basic type checking. + * + * SDL_memcpy and SDL_memmove do not care where you copy memory to and from, + * which can lead to bugs. This macro aims to avoid most of those bugs by + * making sure that the source and destination are both pointers to objects + * that are the same size. It does not check that the objects are the same + * _type_, just that the copy will not overflow either object. + * + * The size check happens at compile time, and the compiler will throw an + * error if the objects are different sizes. + * + * Generally this is intended to copy a single object, not an array. + * + * This macro looks like it double-evaluates its parameters, but the extras + * them are in `sizeof` sections, which generate no code nor side-effects. + * + * \param dst a pointer to the destination object. Must not be NULL. + * \param src a pointer to the source object. Must not be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ #define SDL_copyp(dst, src) \ { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) +/** + * Copy memory ranges that might overlap. + * + * It is okay for the memory regions to overlap. If you are confident that the + * regions never overlap, using SDL_memcpy() may improve performance. + * + * \param dst The destination memory region. Must not be NULL. + * \param src The source memory region. Must not be NULL. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memcpy + */ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memmove */ @@ -949,7 +2527,44 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, S #define SDL_memmove memmove #endif +/** + * Initialize all bytes of buffer of memory to a specific value. + * + * This function will set `len` bytes, pointed to by `dst`, to the value + * specified in `c`. + * + * Despite `c` being an `int` instead of a `char`, this only operates on + * bytes; `c` must be a value between 0 and 255, inclusive. + * + * \param dst the destination memory region. Must not be NULL. + * \param c the byte value to set. + * \param len the length, in bytes, to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); + +/** + * Initialize all 32-bit words of buffer of memory to a specific value. + * + * This function will set a buffer of `dwords` Uint32 values, pointed to by + * `dst`, to the value specified in `val`. + * + * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited + * to a range of 0-255. + * + * \param dst the destination memory region. Must not be NULL. + * \param val the Uint32 value to set. + * \param dwords the number of Uint32 values to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); /* Take advantage of compiler optimizations for memset */ @@ -960,18 +2575,255 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo #define SDL_memset memset #endif +/** + * Clear an object's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an object, not a pointer to an object, nor an array. + * + * \param x the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zerop + * \sa SDL_zeroa + */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) + +/** + * Clear an object's memory to zero, using a pointer. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires a pointer to an object, not an object itself, nor an array. + * + * \param x a pointer to the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) + +/** + * Clear an array's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the array size, so + * there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an array, not an object, nor a pointer to an object. + * + * \param x an array to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) + +/** + * Compare two buffers of memory. + * + * \param s1 the first buffer to compare. NULL is not permitted! + * \param s2 the second buffer to compare. NULL is not permitted! + * \param len the number of bytes to compare between the buffers. + * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is + * "greater than" s2, and zero if the buffers match exactly for `len` + * bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); +/** + * This works exactly like wcslen() but doesn't require access to a C runtime. + * + * Counts the number of wchar_t values in `wstr`, excluding the null + * terminator. + * + * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \returns the length (in wchar_t values, excluding the null terminator) of + * `wstr`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcsnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); + +/** + * This works exactly like wcsnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the + * null terminator. + * + * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * Also, `maxlen` is a count of wide characters, not bytes! + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \param maxlen The maximum amount of wide characters to count. + * \returns the length (in wide characters, excluding the null terminator) of + * `wstr` but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * Copy a wide string. + * + * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then + * appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` is 0, no wide characters are copied and no null terminator is + * written. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated wide string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcat + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \param src The second null-terminated wide string. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Allocate a copy of a wide string. + * + * This allocates enough space for a null-terminated copy of `wstr`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param wstr the string to copy. + * \returns a pointer to the newly-allocated wide string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); + +/** + * Search a wide string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); + +/** + * Search a wide string, up to n wide chars, for the first instance of a + * specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * value to end the string, or `maxlen` wide character have been examined. It + * is possible to use this function on a wide string without a null + * terminator. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \param maxlen the maximum number of wide characters to search in + * `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -989,7 +2841,7 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); @@ -1020,7 +2872,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); @@ -1050,7 +2902,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t * * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); @@ -1092,19 +2944,228 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); +/** + * This works exactly like strlen() but doesn't require access to a C runtime. + * + * Counts the bytes in `str`, excluding the null terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the length (in bytes, excluding the null terminator) of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); + +/** + * This works exactly like strnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null + * terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \param maxlen The maximum amount of bytes to count. + * \returns the length (in bytes, excluding the null terminator) of `src` but + * never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * Copy a string. + * + * This function copies up to `maxlen` - 1 characters from `src` to `dst`, + * then appends a null terminator. + * + * If `maxlen` is 0, no characters are copied and no null terminator is + * written. + * + * If you want to copy an UTF-8 string but need to ensure that multi-byte + * sequences are not truncated, consider using SDL_utf8strlcpy(). + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated string to copy. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param dst_bytes The length (in bytes) of the destination buffer. Must not + * be 0. + * \returns the number of bytes written, excluding the null terminator. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \param src The second null-terminated string. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of the + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Allocate a copy of a string. + * + * This allocates enough space for a null-terminated copy of `str`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); + +/** + * Allocate a copy of a string, up to n characters. + * + * This allocates enough space for a null-terminated copy of `str`, up to + * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into + * this space. + * + * If the string is longer than `maxlen` bytes, the returned string will be + * `maxlen` bytes long, plus a null-terminator character that isn't included + * in the count. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \param maxlen the maximum length of the copied string, not counting the + * null-terminator character. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); + +/** + * Reverse a string's contents. + * + * This reverses a null-terminated string in-place. Only the content of the + * string is reversed; the null-terminator character remains at the end of the + * reversed string. + * + * **WARNING**: This function reverses the _bytes_ of the string, not the + * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this + * will ruin the string data. You should only use this function on strings + * that are completely comprised of low ASCII characters. + * + * \param str the string to reverse. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -1122,7 +3183,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strlwr */ @@ -1143,34 +3204,592 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strupr */ extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); +/** + * Search a string for the first instance of a specific byte. + * + * The search ends once it finds the requested byte value, or a null + * terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the first instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); + +/** + * Search a string for the last instance of a specific byte. + * + * The search must go until it finds a null terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the last instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); + +/** + * Search a string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); + +/** + * Search a string, up to n bytes, for the first instance of a specific + * substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string, or `maxlen` bytes have been examined. It is + * possible to use this function on a string without a null terminator. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \param maxlen the maximum number of bytes to search in `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); + +/** + * Search a UTF-8 string for the first instance of a specific substring, + * case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); -extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr); + +/** + * This works exactly like strtok_r() but doesn't require access to a C + * runtime. + * + * Break a string up into a series of tokens. + * + * To start tokenizing a new string, `str` should be the non-NULL address of + * the string to start tokenizing. Future calls to get the next token from the + * same string should specify a NULL. + * + * Note that this function will overwrite pieces of `str` with null chars to + * split it into tokens. This function cannot be used with const/read-only + * strings! + * + * `saveptr` just needs to point to a `char *` that can be overwritten; SDL + * will use this to save tokenizing state between calls. It is initialized if + * `str` is non-NULL, and used to resume tokenizing when `str` is NULL. + * + * \param str the string to tokenize, or NULL to continue tokenizing. + * \param delim the delimiter string that separates tokens. + * \param saveptr pointer to a char *, used for ongoing state. + * \returns A pointer to the next token, or NULL if no tokens remain. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr); + +/** + * Count the number of codepoints in a UTF-8 string. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strlen(). + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \returns The length (in codepoints, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strnlen + * \sa SDL_strlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); + +/** + * Count the number of codepoints in a UTF-8 string, up to n bytes. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strnlen(). + * + * The counting stops at `bytes` bytes (not codepoints!). This seems + * counterintuitive, but makes it easy to express the total size of the + * string's buffer. + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \param bytes The maximum amount of bytes to count. + * \returns The length (in codepoints, excluding the null terminator) of `src` + * but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strlen + * \sa SDL_strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); +/** + * Convert an integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +/** + * Convert an unsigned integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_itoa + * \sa SDL_ultoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); + +/** + * Convert a long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ultoa + * \sa SDL_itoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); + +/** + * Convert an unsigned long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +#ifndef SDL_NOLONGLONG + +/** + * Convert a long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ulltoa + * \sa SDL_itoa + * \sa SDL_ltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); + +/** + * Convert an unsigned long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); +#endif + +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to + * `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +#ifndef SDL_NOLONGLONG + +/** + * Parse a `long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long long`, the result is + * clamped to the minimum and maximum representable `long long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long long`, or 0 if no number could be + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); +#endif + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. The handling of + * scientific and hexadecimal notation is unspecified. + * - Whether or not INF and NAN can be parsed is unspecified. + * - The precision of the result is unspecified. + * + * \param str the null-terminated string to read. Must not be NULL. + * \param endp if not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \returns the parsed `double`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /** @@ -1189,7 +3808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); @@ -1219,7 +3838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); @@ -1247,7 +3866,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); @@ -1287,20 +3906,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + /** * The Unicode REPLACEMENT CHARACTER codepoint. * - * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string - * with encoding errors. + * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they + * encounter a UTF-8 string with encoding errors. * * This tends to render as something like a question mark in most places. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * + * \sa SDL_StepBackUTF8 * \sa SDL_StepUTF8 */ #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD @@ -1346,10 +3984,41 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); +/** + * Decode a UTF-8 string in reverse, one Unicode codepoint at a time. + * + * This will go to the start of the previous Unicode codepoint in the string, + * move `*pstr` to that location and return that codepoint. + * + * If `*pstr` is already at the start of the string), it will not advance + * `*pstr` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameter each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT. + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param start a pointer to the beginning of the UTF-8 string. + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \returns the previous Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr); + /** * Convert a single Unicode codepoint to UTF-8. * @@ -1375,18 +4044,200 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); - +/** + * This works exactly like sscanf() but doesn't require access to a C runtime. + * + * Scan a string, matching a format string, converting each '%' item and + * storing it to pointers provided through variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); + +/** + * This works exactly like vsscanf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_sscanf(), except it takes a `va_list` instead + * of using `...` variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` of pointers to values to be filled in with scanned + * items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like snprintf() but doesn't require access to a C + * runtime. + * + * Format a string of up to `maxlen`-1 bytes, converting each '%' item with + * values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * bytes will be written at all. + * + * This function returns the number of _bytes_ (not _characters_) that should + * be written, excluding the null-terminator character. If this returns a + * number >= `maxlen`, it means the output string was truncated. A negative + * return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * This works exactly like swprintf() but doesn't require access to a C + * runtime. + * + * Format a wide string of up to `maxlen`-1 wchar_t values, converting each + * '%' item with values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide + * characters will be written at all. + * + * This function returns the number of _wide characters_ (not _codepoints_) + * that should be written, excluding the null-terminator character. If this + * returns a number >= `maxlen`, it means the output string was truncated. A + * negative return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the wide string into. Must not be NULL. + * \param maxlen the maximum wchar_t values to write, including the + * null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like vsnprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); + +/** + * This works exactly like vswprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_swprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum wide characters to write, including the + * null-terminator. + * \param fmt a printf-style format wide string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like asprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it allocates a buffer large + * enough to hold the output string on behalf of the caller. + * + * On success, this function returns the number of bytes (not characters) + * comprising the output string, not counting the null-terminator character, + * and sets `*strp` to the newly-allocated string. + * + * On error, this function returns a negative number, and the value of `*strp` + * is undefined. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * This works exactly like vasprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_asprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** @@ -1401,7 +4252,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR * \threadsafety This should be called on the same thread that calls * SDL_rand*() * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits @@ -1436,7 +4287,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_randf @@ -1459,7 +4310,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_rand @@ -1481,7 +4332,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf(void); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_randf @@ -1516,7 +4367,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits_r @@ -1543,7 +4394,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_bits_r * \sa SDL_rand_r @@ -1569,18 +4420,34 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_r * \sa SDL_randf_r */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); - #ifndef SDL_PI_D + +/** + * The value of Pi, as a double-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_F + */ #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ #endif + #ifndef SDL_PI_F + +/** + * The value of Pi, as a single-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_D + */ #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ #endif @@ -1606,7 +4473,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acosf * \sa SDL_asin @@ -1636,7 +4503,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acos * \sa SDL_asinf @@ -1666,7 +4533,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asinf * \sa SDL_acos @@ -1696,7 +4563,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asin * \sa SDL_acosf @@ -1728,7 +4595,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atanf * \sa SDL_atan2 @@ -1760,7 +4627,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan * \sa SDL_atan2f @@ -1796,7 +4663,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1832,7 +4699,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1858,7 +4725,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceilf * \sa SDL_floor @@ -1886,7 +4753,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceil * \sa SDL_floorf @@ -1915,7 +4782,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabs @@ -1941,7 +4808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabsf @@ -1968,7 +4835,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cosf * \sa SDL_acos @@ -1996,7 +4863,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cos * \sa SDL_acosf @@ -2029,7 +4896,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_expf * \sa SDL_log @@ -2061,7 +4928,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_exp * \sa SDL_logf @@ -2083,7 +4950,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabsf */ @@ -2104,7 +4971,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabs */ @@ -2128,7 +4995,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floorf * \sa SDL_ceil @@ -2156,7 +5023,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floor * \sa SDL_ceilf @@ -2184,7 +5051,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_truncf * \sa SDL_fmod @@ -2213,7 +5080,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_trunc * \sa SDL_fmodf @@ -2242,7 +5109,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmodf * \sa SDL_modf @@ -2272,7 +5139,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmod * \sa SDL_truncf @@ -2292,7 +5159,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinff */ @@ -2306,7 +5173,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinf */ @@ -2320,7 +5187,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnanf */ @@ -2334,7 +5201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnan */ @@ -2362,7 +5229,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_logf * \sa SDL_log10 @@ -2392,7 +5259,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log * \sa SDL_expf @@ -2421,7 +5288,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10f * \sa SDL_log @@ -2451,7 +5318,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10 * \sa SDL_logf @@ -2471,7 +5338,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modff * \sa SDL_trunc @@ -2491,7 +5358,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modf * \sa SDL_truncf @@ -2523,7 +5390,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_powf * \sa SDL_exp @@ -2555,7 +5422,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_pow * \sa SDL_expf @@ -2582,7 +5449,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_roundf * \sa SDL_lround @@ -2611,7 +5478,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_round * \sa SDL_lroundf @@ -2640,7 +5507,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lroundf * \sa SDL_round @@ -2669,7 +5536,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lround * \sa SDL_roundf @@ -2697,7 +5564,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbnf * \sa SDL_pow @@ -2722,7 +5589,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbn * \sa SDL_powf @@ -2749,7 +5616,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sinf * \sa SDL_asin @@ -2765,7 +5632,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * Range: `-1 <= y <= 1` * * This function operates on single-precision floating point values, use - * SDL_sinf for double-precision floats. + * SDL_sin for double-precision floats. * * This function may use a different approximation across different versions, * platforms and configurations. i.e, it can return a different value given @@ -2777,7 +5644,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sin * \sa SDL_asinf @@ -2805,7 +5672,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrtf */ @@ -2831,7 +5698,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrt */ @@ -2857,7 +5724,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tanf * \sa SDL_sin @@ -2887,7 +5754,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tan * \sa SDL_sinf @@ -2897,12 +5764,13 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); */ extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); -/* The SDL implementation of iconv() returns these error codes */ -#define SDL_ICONV_ERROR (size_t)-1 -#define SDL_ICONV_E2BIG (size_t)-2 -#define SDL_ICONV_EILSEQ (size_t)-3 -#define SDL_ICONV_EINVAL (size_t)-4 - +/** + * An opaque handle representing string encoding conversion state. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + */ typedef struct SDL_iconv_data_t *SDL_iconv_t; /** @@ -2914,7 +5782,7 @@ typedef struct SDL_iconv_data_t *SDL_iconv_t; * \returns a handle that must be freed with SDL_iconv_close, or * SDL_ICONV_ERROR on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_close @@ -2929,7 +5797,7 @@ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, * \param cd The character set conversion handle. * \returns 0 on success, or -1 on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_open @@ -2941,7 +5809,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * This function converts text between encodings, reading from and writing to * a buffer. * - * It returns the number of succesful conversions. + * It returns the number of succesful conversions on success. On error, + * SDL_ICONV_E2BIG is returned when the output buffer is too small, or + * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, + * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte sequence. On + * error, this is the location of the problematic input sequence. On + * success, this is the end of the input sequence. + * - inbytesleft will be set to the number of bytes left to convert, which + * will be 0 on success. + * - outbuf will point to the location where to store the next output byte. + * - outbytesleft will be set to the number of bytes left in the output + * buffer. * * \param cd The character set conversion context, created in * SDL_iconv_open(). @@ -2950,23 +5833,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * \param inbytesleft The number of bytes in the input buffer. * \param outbuf Address of variable that points to the output buffer. * \param outbytesleft The number of bytes in the output buffer. - * \returns the number of conversions on success, else SDL_ICONV_E2BIG is - * returned when the output buffer is too small, or SDL_ICONV_EILSEQ - * is returned when an invalid input sequence is encountered, or - * SDL_ICONV_EINVAL is returned when an incomplete input sequence is - * encountered. + * \returns the number of conversions on success, or a negative error code. * - * On exit: - * - * - inbuf will point to the beginning of the next multibyte - * sequence. On error, this is the location of the problematic - * input sequence. On success, this is the end of the input - * sequence. - inbytesleft will be set to the number of bytes left - * to convert, which will be 0 on success. - outbuf will point to - * the location where to store the next output byte. - outbytesleft - * will be set to the number of bytes left in the output buffer. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -2976,6 +5845,12 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); +#define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */ +#define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */ +#define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */ +#define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */ + + /** * Helper function to convert a string's encoding in one call. * @@ -2995,7 +5870,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, * \param inbytesleft the size of the input string _in bytes_. * \returns a new string, converted to the new encoding, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -3006,12 +5881,65 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *inbuf, size_t inbytesleft); -/* Some helper macros for common cases... */ +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) + /* force builds using Clang's static analysis tools to use literal C runtime here, since there are possibly tests that are ineffective otherwise. */ #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) @@ -3034,6 +5962,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include @@ -3073,6 +6004,7 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #define SDL_wcsncmp wcsncmp #define SDL_strcasecmp strcasecmp #define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk #define SDL_sscanf sscanf #define SDL_vsscanf vsscanf #define SDL_snprintf snprintf @@ -3082,29 +6014,27 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); /** * Multiply two integers, checking for overflow. * - * If `a * b` would overflow, return -1. + * If `a * b` would overflow, return false. * - * Otherwise store `a * b` via ret and return 0. + * Otherwise store `a * b` via ret and return true. * * \param a the multiplicand. * \param b the multiplier. - * \param ret on non-overflow output, stores the multiplication result. May + * \param ret on non-overflow output, stores the multiplication result, may * not be NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is multiplied without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) { if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; + return false; } *ret = a * b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION @@ -3112,60 +6042,72 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, /* This needs to be wrapped in an inline rather than being a direct #define, * because __builtin_mul_overflow() is type-generic, but we want to be * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_mul_overflow(a, b, ret) == 0); } -#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) #endif #endif /** * Add two integers, checking for overflow. * - * If `a + b` would overflow, return -1. + * If `a + b` would overflow, return false. * - * Otherwise store `a + b` via ret and return 0. + * Otherwise store `a + b` via ret and return true. * * \param a the first addend. * \param b the second addend. - * \param ret on non-overflow output, stores the addition result. May not be + * \param ret on non-overflow output, stores the addition result, may not be * NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is added without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) { if (b > SDL_SIZE_MAX - a) { - return -1; + return false; } *ret = a + b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION #if SDL_HAS_BUILTIN(__builtin_add_overflow) /* This needs to be wrapped in an inline rather than being a direct #define, * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_add_overflow(a, b, ret) == 0); } -#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) #endif #endif /* This is a generic function pointer which should be cast to the type you expect */ -#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) typedef void *SDL_FunctionPointer; #else typedef void (*SDL_FunctionPointer)(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_storage.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_storage.h index 91a90bc..8b89ace 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_storage.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_storage.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,222 @@ /** * # CategoryStorage * - * SDL storage container management. + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) { + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(data); + * } + * } + * } + * + * void ReadSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * + * void WriteSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(NULL, 0); + * if (title == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(title)) { + * SDL_Delay(1); + * } + * + * for (size_t i = 0; i < numFiles; i += 1) { + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) { + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * } + * + * SDL_CloseStorage(title); + * } + * + * void ReadSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) { + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * + * void WriteSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. */ #ifndef SDL_storage_h_ @@ -40,8 +255,6 @@ extern "C" { #endif -/* !!! FIXME: Don't let this ship without async R/W support!!! */ - /** * Function interface for SDL_Storage. * @@ -52,44 +265,61 @@ extern "C" { * It is not usually necessary to do this; SDL provides standard * implementations for many things you might expect to do with an SDL_Storage. * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_StorageInterface { + /* The version of this interface */ + Uint32 version; + /* Called when the storage is closed */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); /* Optional, returns whether the storage is currently ready for access */ - SDL_bool (SDLCALL *ready)(void *userdata); + bool (SDLCALL *ready)(void *userdata); /* Enumerate a directory, optional for write-only storage */ - SDL_bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); /* Get path information, optional for write-only storage */ - SDL_bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); /* Read a file from storage, optional for write-only storage */ - SDL_bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); /* Write a file to storage, optional for read-only storage */ - SDL_bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); /* Create a directory, optional for read-only storage */ - SDL_bool (SDLCALL *mkdir)(void *userdata, const char *path); + bool (SDLCALL *mkdir)(void *userdata, const char *path); /* Remove a file or empty directory, optional for read-only storage */ - SDL_bool (SDLCALL *remove)(void *userdata, const char *path); + bool (SDLCALL *remove)(void *userdata, const char *path); /* Rename a path, optional for read-only storage */ - SDL_bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); /* Copy a file, optional for read-only storage */ - SDL_bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); } SDL_StorageInterface; +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + /** * An abstract interface for filesystem access. * @@ -97,7 +327,7 @@ typedef struct SDL_StorageInterface * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create * an object with a custom implementation using SDL_OpenStorage. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Storage SDL_Storage; @@ -109,7 +339,7 @@ typedef struct SDL_Storage SDL_Storage; * \returns a title storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -132,7 +362,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *overr * \returns a user storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -156,7 +386,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, c * \returns a filesystem storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -176,16 +406,21 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * or SDL_OpenUserStorage(). * - * \param iface the function table to be used by this container. - * \param userdata the pointer that will be passed to the store interface. + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE * \sa SDL_ReadStorageFile * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -196,33 +431,33 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * Closes and frees a storage container. * * \param storage a storage container to close. - * \returns SDL_TRUE if the container was freed with no errors, SDL_FALSE - * otherwise; call SDL_GetError() for more information. Even if the - * function returns an error, the container data will be freed; the - * error is only for informational purposes. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenFileStorage * \sa SDL_OpenStorage * \sa SDL_OpenTitleStorage * \sa SDL_OpenUserStorage */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); /** * Checks if the storage container is ready to use. * - * This function should be called in regular intervals until it returns - * SDL_TRUE - however, it is not recommended to spinwait on this call, as the - * backend may depend on a synchronous message loop. + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. * * \param storage a storage container to query. - * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise. + * \returns true if the container is ready, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); /** * Query the size of a file within a storage container. @@ -230,34 +465,38 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); * \param storage a storage container to query. * \param path the relative path of the file to query. * \param length a pointer to be filled with the file's length. - * \returns SDL_TRUE if the file could be queried or SDL_FALSE on failure; - * call SDL_GetError() for more information. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); /** * Synchronously read a file from a storage container into a client-provided * buffer. * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * * \param storage a storage container to read from. * \param path the relative path of the file to read. * \param destination a client-provided buffer to read the file into. * \param length the length of the destination buffer. - * \returns SDL_TRUE if the file was read or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageFileSize * \sa SDL_StorageReady * \sa SDL_WriteStorageFile */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); /** * Synchronously write a file from client memory into a storage container. @@ -266,64 +505,73 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, c * \param path the relative path of the file to write. * \param source a client-provided buffer to write from. * \param length the length of the source buffer. - * \returns SDL_TRUE if the file was written or SDL_FALSE on failure; call + * \returns true if the file was written or false on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageSpaceRemaining * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); /** * Create a directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); /** * Enumerate a directory in a storage container through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); /** * Rename a file or directory in a writable storage container. @@ -331,14 +579,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Copy a file in a writable storage container. @@ -346,14 +594,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Get information about a filesystem path in a storage container. @@ -362,14 +610,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, c * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); /** * Queries the remaining space in a storage container. @@ -377,7 +625,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage * \param storage a storage container to query. * \returns the amount of remaining space, in bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -401,8 +649,11 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param pattern the pattern that files in the directory must match. Can be * NULL. * \param flags `SDL_GLOB_*` bitflags that affect this search. @@ -417,7 +668,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * \threadsafety It is safe to call this function from any thread, assuming * the `storage` object is thread-safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_surface.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_surface.h index aafe574..0752f53 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_surface.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_surface.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,19 @@ /** * # CategorySurface * - * SDL_Surface definition and management functions. + * SDL surfaces are buffers of pixels in system RAM. These are useful for + * passing around and manipulating images that are not stored in GPU memory. + * + * SDL_Surface makes serious efforts to manage images in various formats, and + * provides a reasonable toolbox for transforming the data, including copying + * between surfaces, filling rectangles in the image data, etc. + * + * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not + * provide loaders for various other file formats, but there are several + * excellent external libraries that do, including its own satellite library, + * SDL_image: + * + * https://github.com/libsdl-org/SDL_image */ #ifndef SDL_surface_h_ @@ -47,7 +59,7 @@ extern "C" { * * These are generally considered read-only. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SurfaceFlags; @@ -59,14 +71,14 @@ typedef Uint32 SDL_SurfaceFlags; /** * Evaluates to true if the surface needs to be locked before access. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MUSTLOCK(S) ((((S)->flags & SDL_SURFACE_LOCK_NEEDED)) == SDL_SURFACE_LOCK_NEEDED) /** * The scaling mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ScaleMode { @@ -77,7 +89,7 @@ typedef enum SDL_ScaleMode /** * The flip mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlipMode { @@ -86,8 +98,7 @@ typedef enum SDL_FlipMode SDL_FLIP_VERTICAL /**< flip vertically */ } SDL_FlipMode; -/* Internal surface data */ -typedef struct SDL_SurfaceData SDL_SurfaceData; +#ifndef SDL_INTERNAL /** * A collection of pixels used in software blitting. @@ -104,22 +115,32 @@ typedef struct SDL_SurfaceData SDL_SurfaceData; * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * - * \since This struct is available since SDL 3.0.0. + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface */ -typedef struct SDL_Surface +struct SDL_Surface { - SDL_SurfaceFlags flags; /**< Read-only */ - SDL_PixelFormat format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-only pointer, writable pixels if non-NULL */ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ int refcount; /**< Application reference count, used when freeing surface */ - SDL_SurfaceData *internal; /**< Private */ - -} SDL_Surface; + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ +typedef struct SDL_Surface SDL_Surface; /** * Allocate a new surface with a specific pixel format. @@ -132,7 +153,7 @@ typedef struct SDL_Surface * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurfaceFrom * \sa SDL_DestroySurface @@ -160,7 +181,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurface(int width, int heigh * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -174,9 +195,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurfaceFrom(int width, int h * * \param surface the SDL_Surface to free. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_CreateStackSurface * \sa SDL_CreateSurface * \sa SDL_CreateSurfaceFrom */ @@ -206,7 +226,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface); @@ -221,16 +241,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac * interpreted in color operations. * * \param surface the SDL_Surface structure to update. - * \param colorspace an SDL_ColorSpace value describing the surface + * \param colorspace an SDL_Colorspace value describing the surface * colorspace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); /** * Get the colorspace used by a surface. @@ -243,7 +263,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surfa * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if * the surface is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorspace */ @@ -271,7 +291,7 @@ extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface * the surface didn't have an index format); call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -284,15 +304,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface * * * \param surface the SDL_Surface structure to update. * \param palette the SDL_Palette structure to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); /** * Get the palette used by a surface. @@ -301,7 +321,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, * \returns a pointer to the palette used by the surface, or NULL if there is * no palette used. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfacePalette */ @@ -321,31 +341,30 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \param surface the SDL_Surface structure to update. * \param image a pointer to an alternate SDL_Surface to associate with this * surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages * \sa SDL_SurfaceHasAlternateImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); /** * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true if alternate versions are available or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); /** * Get an array including all versions of a surface. @@ -364,7 +383,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface * * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -380,7 +399,7 @@ extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *sur * * \param surface the SDL_Surface structure to update. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_GetSurfaceImages @@ -401,22 +420,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s * format of the surface will not change. * * \param surface the SDL_Surface structure to be locked. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockSurface(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); /** * Release a surface after directly accessing the pixels. * * \param surface the SDL_Surface structure to be unlocked. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSurface */ @@ -429,18 +448,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * will result in a memory leak. * * \param src the data stream for the surface. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); /** * Load a BMP image from a file. @@ -452,7 +471,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP_IO @@ -471,17 +490,17 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); * * \param surface the SDL_Surface structure containing the image to be saved. * \param dst a data stream to save to. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, - * even in the case of an error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closeio if true, calls SDL_CloseIO() on `dst` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, SDL_bool closeio); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); /** * Save a surface to a file. @@ -494,15 +513,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IO * * \param surface the SDL_Surface structure containing the image to be saved. * \param file a file to save to. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); /** * Set the RLE acceleration hint for a surface. @@ -511,32 +530,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const cha * the surface must be locked before directly accessing the pixels. * * \param surface the SDL_Surface structure to optimize. - * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable - * it. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable RLE acceleration, false to disable it. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface * \sa SDL_LockSurface * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); /** * Returns whether the surface is RLE enabled. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. + * \returns true if the surface is RLE enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceRLE */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); /** * Set the color key (transparent pixel) in a surface. @@ -549,34 +567,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * SDL_MapRGB(). * * \param surface the SDL_Surface structure to update. - * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color - * key. + * \param enabled true to enable color key, false to disable color key. * \param key the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorKey * \sa SDL_SetSurfaceRLE * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); /** * Returns whether the surface has a color key. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. + * \returns true if the surface has a color key, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); /** * Get the color key (transparent pixel) for a surface. @@ -584,19 +601,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface * The color key is a pixel of the format used by the surface, as generated by * SDL_MapRGB(). * - * If the surface doesn't have color key enabled this function returns -1. + * If the surface doesn't have color key enabled this function returns false. * * \param surface the SDL_Surface structure to query. * \param key a pointer filled in with the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); /** * Set an additional color value multiplied into blit operations. @@ -611,15 +628,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface * \param r the red color value multiplied into blit operations. * \param g the green color value multiplied into blit operations. * \param b the blue color value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); /** @@ -629,15 +646,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); /** * Set an additional alpha value used in blit operations. @@ -649,30 +666,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param alpha the alpha value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); /** * Get the additional alpha value used in blit operations. * * \param surface the SDL_Surface structure to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); /** * Set the blend mode used for blit operations. @@ -683,28 +700,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); /** * Get the blend mode used for blit operations. * * \param surface the SDL_Surface structure to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); /** * Set the clipping rectangle for a surface. @@ -718,14 +735,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surfac * \param surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); /** * Get the clipping rectangle for a surface. @@ -737,26 +754,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for * the surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); /** * Flip a surface vertically or horizontally. * * \param surface the surface to flip. * \param flip the direction to flip. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); /** * Creates a new surface identical to the existing surface. @@ -770,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_F * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -789,7 +806,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surf * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -814,7 +831,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface, * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurfaceAndColorspace * \sa SDL_DestroySurface @@ -840,10 +857,9 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurface - * \sa SDL_ConvertSurface * \sa SDL_DestroySurface */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props); @@ -859,14 +875,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Su * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixelsAndColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); /** * Copy a block of pixels of one format and colorspace to another format and @@ -875,27 +891,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SD * \param width the width of the block to copy, in pixels. * \param height the height of the block to copy, in pixels. * \param src_format an SDL_PixelFormat value of the `src` pixels format. - * \param src_colorspace an SDL_ColorSpace value describing the colorspace of + * \param src_colorspace an SDL_Colorspace value describing the colorspace of * the `src` pixels. * \param src_properties an SDL_PropertiesID with additional source color * properties, or 0. * \param src a pointer to the source pixels. * \param src_pitch the pitch of the source pixels, in bytes. * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. - * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of * the `dst` pixels. * \param dst_properties an SDL_PropertiesID with additional destination color * properties, or 0. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixels */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); /** * Premultiply the alpha on a block of pixels. @@ -910,14 +926,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, i * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with premultiplied pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); /** * Premultiply the alpha in a surface. @@ -925,14 +941,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, * This is safe to use with src == dst, but not for other overlapping areas. * * \param surface the surface to modify. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); /** * Clear a surface with a specific color, with floating point precision. @@ -947,12 +963,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *su * \param g the green component of the pixel, normally in the range 0-1. * \param b the blue component of the pixel, normally in the range 0-1. * \param a the alpha component of the pixel, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); /** * Perform a fast fill of a rectangle with a specific color. @@ -970,14 +986,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, floa * \param rect the SDL_Rect structure representing the rectangle to fill, or * NULL to fill the entire surface. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); /** * Perform a fast fill of a set of rectangles with a specific color. @@ -995,22 +1011,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const * \param rects an array of SDL_Rects representing the rectangles to fill. * \param count the number of rectangles in the array. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); /** - * Performs a fast blit from the source surface to the destination surface. + * Performs a fast blit from the source surface to the destination surface + * with clipping. * - * This assumes that the source and destination rectangles are the same size. * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or - * `dst`) is copied. The final blit rectangles are saved in `srcrect` and - * `dstrect` after all clipping is performed. + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. + * + * The final blit rectangles are saved in `srcrect` and `dstrect` after all + * clipping is performed. * * The blit function should not be called on a locked surface. * @@ -1066,18 +1084,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, cons * height are ignored, and are copied from `srcrect`. If you * want a specific width and height, you should use * SDL_BlitSurfaceScaled(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform low-level surface blitting only. @@ -1091,18 +1109,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit to a destination surface, which may be of a different @@ -1116,18 +1134,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, * the destination surface, or NULL to fill the entire * destination surface. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform low-level surface scaled blitting only. @@ -1142,18 +1160,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, con * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform a tiled blit to a destination surface, which may be of a different @@ -1168,18 +1186,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled and tiled blit to a destination surface, which may be of a @@ -1198,18 +1216,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, cons * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit using the 9-grid algorithm to a destination surface, @@ -1235,18 +1253,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface * * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Map an RGB triple to an opaque pixel value for a surface. @@ -1272,7 +1290,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, cons * \param b the blue component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGBA */ @@ -1303,7 +1321,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 * \param a the alpha component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGB */ @@ -1329,12 +1347,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint * ignore this channel. * \param a a pointer filled in with the alpha channel, 0-255, or NULL to * ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Retrieves a single pixel from a surface. @@ -1353,12 +1371,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, * 0-1, or NULL to ignore this channel. * \param a a pointer filled in with the alpha channel, normally in the range * 0-1, or NULL to ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); /** * Writes a single pixel to a surface. @@ -1376,12 +1394,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surf * \param g the green channel value, 0-255. * \param b the blue channel value, 0-255. * \param a the alpha channel value, 0-255. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Writes a single pixel to a surface. @@ -1396,12 +1414,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, * \param g the green channel value, normally in the range 0-1. * \param b the blue channel value, normally in the range 0-1. * \param a the alpha channel value, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_system.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_system.h index 17ac0a1..294089f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_system.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_system.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,13 @@ /** * # CategorySystem * - * Platform-specific SDL API functions. + * Platform-specific SDL API functions. These are functions that deal with + * needs of specific operating systems, that didn't make sense to offer as + * platform-independent, generic APIs. + * + * Most apps can make do without these functions, but they can be useful for + * integrating with other parts of a specific system, adding platform-specific + * polish to an app, or solving problems that only affect one target. */ #ifndef SDL_system_h_ @@ -31,7 +37,6 @@ #include #include #include -#include #include #include @@ -44,16 +49,15 @@ extern "C" { /* * Platform specific functions for Windows */ -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) typedef struct tagMSG MSG; /** * A callback to be used with SDL_SetWindowsMessageHook. * - * This callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * This callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * As this is processing a message directly from the Windows event loop, this * callback should do the minimum required work and return quickly. @@ -61,36 +65,35 @@ typedef struct tagMSG MSG; * \param userdata the app-defined pointer provided to * SDL_SetWindowsMessageHook. * \param msg a pointer to a Win32 event structure to process. - * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it. + * \returns true to let event continue on, false to drop it. * * \threadsafety This may only be called (by SDL) from the thread handling the * Windows event loop. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetWindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ -typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); /** * Set a callback for every Windows message, run before TranslateMessage(). * - * The callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_WindowsMessageHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) @@ -104,14 +107,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo * \returns the D3D9 adapter index on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ - -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) - /** * Get the DXGI Adapter and Output indices for the specified display. * @@ -122,33 +121,55 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displ * \param displayID the instance of the display to query. * \param adapterIndex a pointer to be filled in with the adapter index. * \param outputIndex a pointer to be filled in with the output index. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + /* * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _XEvent XEvent; -typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); + +/** + * A callback to be used with SDL_SetX11EventHook. + * + * This callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * As this is processing an event directly from the X11 event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to SDL_SetX11EventHook. + * \param xevent a pointer to an Xlib XEvent union to process. + * \returns true to let event continue on, false to drop it. + * + * \threadsafety This may only be called (by SDL) from the thread handling the + * X11 event loop. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetX11EventHook + */ +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** * Set a callback for every X11 event. * - * The callback may modify the event, and should return SDL_TRUE if the event - * should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_X11EventHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); @@ -162,12 +183,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, * * \param threadID the Unix thread ID to change priority of. * \param priority the new, Unix-specific, priority value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); /** * Sets the priority (not nice level) and scheduling policy for a thread. @@ -178,12 +199,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, * \param sdlPriority the new SDL_ThreadPriority value. * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, * SCHED_OTHER, etc...). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); #endif /* SDL_PLATFORM_LINUX */ @@ -204,7 +225,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 * \param userdata what was passed as `callbackParam` to * SDL_SetiOSAnimationCallback as `callbackParam`. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ @@ -240,27 +261,27 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSEventPump */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); /** * Use this function to enable or disable the SDL event pump on Apple iOS. * * This function is only available on Apple iOS. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. + * \param enabled true to enable the event pump, false to disable it. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); #endif /* SDL_PLATFORM_IOS */ @@ -286,7 +307,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidActivity */ @@ -311,7 +332,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidJNIEnv */ @@ -349,43 +370,34 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); * * \returns the Android API level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - /** * Query if the application is running on a Chromebook. * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * \returns true if this is a Chromebook, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); /** * Query if the application is running on a Samsung DeX docking station. * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * \returns true if this is a DeX docking station, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); /** * Trigger the Android system back button behavior. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); @@ -393,9 +405,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * See the official Android developer guide for more information: * http://developer.android.com/guide/topics/data/data-storage.html * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 + +/** + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -414,9 +433,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \returns the path used for internal storage or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidExternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void); @@ -431,7 +451,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void) * \returns the current state of external storage, or 0 if external storage is * currently unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStoragePath */ @@ -453,9 +473,11 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); * \returns the path used for external storage for this application on success * or NULL on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void); @@ -474,12 +496,25 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) * \returns the path used for caches for this application on success or NULL * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidExternalStoragePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - -typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted); +/** + * Callback that presents a response from a SDL_RequestAndroidPermission call. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param permission the Android-specific permission name that was requested. + * \param granted true if permission is granted, false if denied. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RequestAndroidPermission + */ +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** * Request permissions at runtime, asynchronously. @@ -500,18 +535,22 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * like memory running out. Normally there will be a yes or no to the request * through the callback. * + * For the `permission` parameter, choose a value from here: + * + * https://developer.android.com/reference/android/Manifest.permission + * * \param permission the permission to request. * \param cb the callback to trigger when the request has a response. * \param userdata an app-controlled pointer that is passed to the callback. - * \returns SDL_TRUE if the request was submitted, SDL_FALSE if there was an - * error submitting. The result of the request is only ever reported + * \returns true if the request was submitted, false if there was an error + * submitting. The result of the request is only ever reported * through the callback, not this return value. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); /** * Shows an Android toast notification. @@ -532,14 +571,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *pe * \param gravity where the notification should appear on the screen. * \param xoffset set this parameter only when gravity >=0. * \param yoffset set this parameter only when gravity >=0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); /** * Send a user command to SDLActivity. @@ -548,111 +587,63 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, i * * \param command user command that must be greater or equal to 0x8000. * \param param user parameter. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); #endif /* SDL_PLATFORM_ANDROID */ -/* - * Platform specific functions for WinRT - */ -#ifdef SDL_PLATFORM_WINRT - -/** - * WinRT / Windows Phone path types - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_Path -{ - /** The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily(); - -#endif /* SDL_PLATFORM_WINRT */ - /** * Query if the current device is a tablet. * - * If SDL can't determine this, it will return SDL_FALSE. + * If SDL can't determine this, it will return false. * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * \returns true if the device is a tablet, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_Sandbox +{ + SDL_SANDBOX_NONE = 0, + SDL_SANDBOX_UNKNOWN_CONTAINER, + SDL_SANDBOX_FLATPAK, + SDL_SANDBOX_SNAP, + SDL_SANDBOX_MACOS +} SDL_Sandbox; + +/** + * Get the application sandbox environment, if any. + * + * \returns the application sandbox environment or SDL_SANDBOX_NONE if the + * application is not running in a sandbox environment. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void); + /* Functions used by iOS app delegates to notify SDL about state changes. */ @@ -669,7 +660,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); @@ -686,7 +677,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); @@ -703,7 +694,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); @@ -720,7 +711,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); @@ -737,7 +728,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); @@ -754,7 +745,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); @@ -773,7 +764,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); #endif @@ -794,12 +785,12 @@ typedef struct XUser *XUserHandle; * leak. * * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); /** * Gets a reference to the default user handle for GDK. @@ -809,12 +800,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTa * * \param outUserHandle a pointer to be filled in with the default user * handle. - * \returns SDL_TRUE if success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); #endif diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_thread.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_thread.h index 0fdc8a0..277535f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_thread.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_thread.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,19 @@ /** * # CategoryThread * - * SDL thread management routines. + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. */ #include @@ -34,9 +46,8 @@ /* Thread synchronization primitives */ #include -#include -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +#if defined(SDL_PLATFORM_WINDOWS) #include /* _beginthreadex() and _endthreadex() */ #endif @@ -51,7 +62,7 @@ extern "C" { * * These are opaque data. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -65,7 +76,7 @@ typedef struct SDL_Thread SDL_Thread; * application will operate on, but having a way to uniquely identify a thread * can be useful at times. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetThreadID * \sa SDL_GetCurrentThreadID @@ -78,7 +89,7 @@ typedef Uint64 SDL_ThreadID; * 0 is the invalid ID. An app can create these and then set data for these * IDs that is unique to each thread. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetTLS * \sa SDL_SetTLS @@ -90,11 +101,11 @@ typedef SDL_AtomicInt SDL_TLSID; * * SDL will make system changes as necessary in order to apply the thread * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, @@ -103,13 +114,30 @@ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_TIME_CRITICAL } SDL_ThreadPriority; +/** + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + */ +typedef enum SDL_ThreadState +{ + SDL_THREAD_UNKNOWN, /**< The thread is not valid */ + SDL_THREAD_ALIVE, /**< The thread is currently running */ + SDL_THREAD_DETACHED, /**< The thread is detached and can't be waited on */ + SDL_THREAD_COMPLETE /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} SDL_ThreadState; + /** * The function passed to SDL_CreateThread() as the new thread's entry point. * * \param data what was passed as `data` to SDL_CreateThread(). * \returns a value that can be reported through SDL_WaitThread(). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -179,7 +207,7 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThreadWithProperties * \sa SDL_WaitThread @@ -245,7 +273,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -263,7 +291,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop /* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ #ifndef SDL_WIKI_DOCUMENTATION_SECTION -# if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +# if defined(SDL_PLATFORM_WINDOWS) # ifndef SDL_BeginThreadFunction # define SDL_BeginThreadFunction _beginthreadex # endif @@ -300,7 +328,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -314,7 +342,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunct * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -334,7 +362,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S * \returns a pointer to a UTF-8 string that names the specified thread, or * NULL if it doesn't have a name. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); @@ -350,7 +378,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); * * \returns the ID of the current thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetThreadID */ @@ -367,7 +395,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentThreadID */ @@ -381,25 +409,25 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * an administrator account. Be prepared for this to fail. * * \param priority the SDL_ThreadPriority to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); /** * Wait for a thread to finish. * - * Threads that haven't been detached will remain (as a "zombie") until this - * function cleans them up. Not doing so is a resource leak. + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. * * Once a thread has been cleaned up through this function, the SDL_Thread * that references it becomes invalid and should not be referenced again. As * such, only one thread may call SDL_WaitThread() on another. * - * The return code for the thread function is placed in the area pointed to by - * `status`, if `status` is not NULL. + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. * * You may not wait on a thread that has been used in a call to * SDL_DetachThread(). Use either that function or this one, but not both, or @@ -412,17 +440,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority pr * * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. - * \param status pointer to an integer that will receive the value returned - * from the thread function by its 'return', or NULL to not - * receive such value back. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_DetachThread */ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status); +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *thread); + /** * Let a thread clean up on exit without intervention. * @@ -452,7 +493,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status) * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -468,7 +509,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread *thread); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -481,7 +522,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetTLS(SDL_TLSID *id); * * \param value a pointer previously handed to SDL_SetTLS. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -504,16 +545,16 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * \param value the value to associate with the ID for the current thread. * \param destructor a function called when the thread exits, to free the * value, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTLS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. @@ -524,7 +565,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CleanupTLS(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_time.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_time.h index 86c1fad..b6d3f6d 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_time.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_time.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ freely, subject to the following restrictions: * # CategoryTime * * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. */ #include @@ -41,7 +49,7 @@ extern "C" { * A structure holding a calendar date and time broken down into its * components. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DateTime { @@ -59,7 +67,7 @@ typedef struct SDL_DateTime /** * The preferred date format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -73,7 +81,7 @@ typedef enum SDL_DateFormat /** * The preferred time format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -95,24 +103,24 @@ typedef enum SDL_TimeFormat * format, may be NULL. * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * format, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); /** * Gets the current value of the system realtime clock in nanoseconds since * Jan 1, 1970 in Universal Coordinated Time (UTC). * * \param ticks the SDL_Time to hold the returned tick count. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); /** * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in @@ -123,12 +131,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \param localTime the resulting SDL_DateTime will be expressed in local time * if true, otherwise it will be in Universal Coordinated * Time (UTC). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime); +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); /** * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. @@ -138,12 +146,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_Date * * \param dt the source SDL_DateTime. * \param ticks the resulting SDL_Time. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); /** * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals @@ -157,7 +165,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, * \param dwHighDateTime a pointer filled in with the high portion of the * Windows FILETIME value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); @@ -172,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow * \param dwHighDateTime the high portion of the Windows FILETIME value. * \returns the converted SDL time. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); @@ -184,7 +192,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * \returns the number of days in the requested month or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); @@ -197,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \returns the day of year [0-365] if the date is valid or -1 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); @@ -210,7 +218,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or * -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_timer.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_timer.h index 9d05161..cf94881 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_timer.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_timer.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,20 @@ /** * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. */ #include @@ -38,16 +51,137 @@ extern "C" { #endif /* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_US 1000 + +/** + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND) + +/** + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND) + +/** + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS) + +/** + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS) + +/** + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US) + +/** + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) /** @@ -56,7 +190,9 @@ extern "C" { * \returns an unsigned 64-bit value representing the number of milliseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); @@ -66,7 +202,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); * \returns an unsigned 64-bit value representing the number of nanoseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); @@ -81,7 +219,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); * * \returns the current counter value. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceFrequency */ @@ -92,7 +232,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); * * \returns a platform-specific count per second. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceCounter */ @@ -107,10 +249,33 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * * \param ms the number of milliseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); + /** * Wait a specified number of nanoseconds before returning. * @@ -120,14 +285,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * * \param ns the number of nanoseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS */ -extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); +extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); /** * Definition of the timer ID type. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_TimerID; @@ -151,7 +321,7 @@ typedef Uint32 SDL_TimerID; * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimer */ @@ -160,8 +330,6 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimer() call and should return the next * timer interval. If the value returned from the callback is 0, the timer is @@ -188,7 +356,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimerNS * \sa SDL_RemoveTimer @@ -215,7 +383,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimerNS */ @@ -224,8 +392,6 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimerNS() call and should return the * next timer interval. If the value returned from the callback is 0, the @@ -252,7 +418,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer * \sa SDL_RemoveTimer @@ -263,14 +429,16 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * Remove a timer created with SDL_AddTimer(). * * \param id the ID of the timer to remove. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_touch.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_touch.h index 6889f36..64845a1 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_touch.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_touch.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryTouch * - * SDL touch management. + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. */ #ifndef SDL_touch_h_ @@ -31,7 +42,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -39,25 +49,53 @@ extern "C" { #endif +/** + * A unique ID for a touch device. + * + * This ID is valid for the time the device is connected to the system, and is + * never reused for the lifetime of the application. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_TouchID; + +/** + * A unique ID for a single finger on a touch device. + * + * This ID is valid for the time the finger (stylus, etc) is touching and will + * be unique for all fingers currently in contact, so this ID tracks the + * lifetime of a single continuous touch. This value may represent an index, a + * pointer, or some other unique ID, depending on the platform. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_FingerID; +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_TouchDeviceType { SDL_TOUCH_DEVICE_INVALID = -1, - SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ + SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */ } SDL_TouchDeviceType; /** * Data about a single finger in a multitouch event. * - * Each touch even is a collection of fingers that are simultaneously in + * Each touch event is a collection of fingers that are simultaneously in * contact with the touch device (so a "touch" can be a "multitouch," in * reality), and this struct reports details of the specific fingers. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetTouchFingers */ @@ -69,10 +107,18 @@ typedef struct SDL_Finger float pressure; /**< the quantity of pressure applied, normalized (0...1) */ } SDL_Finger; -/* Used as the device ID for mouse events simulated with touch input */ +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) -/* Used as the SDL_TouchID for touch events simulated with mouse input */ +/** + * The SDL_TouchID for touch events simulated with mouse input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) @@ -89,7 +135,7 @@ typedef struct SDL_Finger * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); @@ -100,7 +146,7 @@ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); * \returns touch device name, or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID); @@ -110,7 +156,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touc * \param touchID the ID of a touch device. * \returns touch device type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); @@ -125,7 +171,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_tray.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_tray.h new file mode 100644 index 0000000..0b05db2 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryTray + * + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. + */ + +#ifndef SDL_tray_h_ +#define SDL_tray_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Tray SDL_Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayMenu SDL_TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayEntry SDL_TrayEntry; + +/** + * Flags that control the creation of system tray entries. + * + * Some of these flags are required; exactly one of them must be specified at + * the time a tray entry is created. Other flags are optional; zero or more of + * those can be OR'ed together with the required flag. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +typedef Uint32 SDL_TrayEntryFlags; + +#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */ +#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */ +#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */ +#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */ +#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */ + +/** + * A callback that is invoked when a tray entry is selected. + * + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param entry the tray entry that was selected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTrayEntryCallback + */ +typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); + +/** + * Create an icon to be placed in the operating system's tray, or equivalent. + * + * Many platforms advise not using a system tray unless persistence is a + * necessary feature. Avoid needlessly creating a tray icon, as the user may + * feel like it clutters their interface. + * + * Using tray icons require the video subsystem. + * + * \param icon a surface to be used as icon. May be NULL. + * \param tooltip a tooltip to be displayed when the mouse hovers the icon in + * UTF-8 encoding. Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenu + * \sa SDL_DestroyTray + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip); + +/** + * Updates the system tray icon's icon. + * + * \param tray the tray icon to be updated. + * \param icon the new icon. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon); + +/** + * Updates the system tray icon's tooltip. + * + * \param tray the tray icon to be updated. + * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip); + +/** + * Create a menu for a system tray. + * + * This should be called at most once per tray icon. + * + * This function does the same thing as SDL_CreateTraySubmenu(), except that + * it takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_GetTrayMenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); + +/** + * Create a submenu for a system tray entry. + * + * This should be called at most once per tray entry. + * + * This function does the same thing as SDL_CreateTrayMenu, except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTraySubmenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry); + +/** + * Gets a previously created tray menu. + * + * You should have called SDL_CreateTrayMenu() on the tray object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTraySubmenu(), except that it + * takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_CreateTrayMenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); + +/** + * Gets a previously created tray entry submenu. + * + * You should have called SDL_CreateTraySubmenu() on the entry object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTrayMenu(), except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_CreateTraySubmenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry); + +/** + * Returns a list of entries in the menu, in order. + * + * \param menu The menu to get entries from. + * \param size An optional pointer to obtain the number of entries in the + * menu. + * \returns a NULL-terminated list of entries within the given menu. The + * pointer becomes invalid when any function that inserts or deletes + * entries in the menu is called. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveTrayEntry + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size); + +/** + * Removes a tray entry. + * + * \param entry The entry to be deleted. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); + +/** + * Insert a tray entry at a given position. + * + * If label is NULL, the entry will be a separator. Many functions won't work + * for an entry that is a separator. + * + * An entry does not need to be destroyed; it will be destroyed with the tray. + * + * \param menu the menu to append the entry to. + * \param pos the desired position for the new entry. Entries at or following + * this place will be moved. If pos is -1, the entry is appended. + * \param label the text to be displayed on the entry, in UTF-8 encoding, or + * NULL for a separator. + * \param flags a combination of flags, some of which are mandatory. + * \returns the newly created entry, or NULL if pos is out of bounds. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TrayEntryFlags + * \sa SDL_GetTrayEntries + * \sa SDL_RemoveTrayEntry + * \sa SDL_GetTrayEntryParent + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags); + +/** + * Sets the label of an entry. + * + * An entry cannot change between a separator and an ordinary entry; that is, + * it is not possible to set a non-NULL label on an entry that has a NULL + * label (separators), or to set a NULL label to an entry that has a non-NULL + * label. The function will silently fail if that happens. + * + * \param entry the entry to be updated. + * \param label the new label for the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryLabel + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label); + +/** + * Gets the label of an entry. + * + * If the returned value is NULL, the entry is a separator. + * + * \param entry the entry to be read. + * \returns the label of the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryLabel + */ +extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be updated. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryChecked + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked); + +/** + * Gets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be read. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryChecked + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is enabled. + * + * \param entry the entry to be updated. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled); + +/** + * Gets whether or not an entry is enabled. + * + * \param entry the entry to be read. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); + +/** + * Sets a callback to be invoked when the entry is selected. + * + * \param entry the entry to be updated. + * \param callback a callback to be invoked when the entry is selected. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata); + +/** + * Simulate a click on a tray entry. + * + * \param entry The entry to activate. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); + +/** + * Gets the menu containing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry); + +/** + * Gets the entry for which the menu is a submenu, if the current menu is a + * submenu. + * + * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent entry. + * \returns the parent entry, or NULL if this menu is not a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTraySubmenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu); + +/** + * Gets the tray for which this menu is the first-level menu, if the current + * menu isn't a submenu. + * + * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent enttrayry. + * \returns the parent tray, or NULL if this menu is a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); + +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_version.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_version.h index c0f518d..55014e3 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_version.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_version.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -30,7 +30,6 @@ #define SDL_version_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -43,7 +42,7 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 3. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MAJOR_VERSION 3 @@ -52,18 +51,18 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 2. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MINOR_VERSION 1 +#define SDL_MINOR_VERSION 2 /** * The current micro (or patchlevel) version of the SDL headers. * * If this were SDL version 3.2.1, this value would be 1. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MICRO_VERSION 2 +#define SDL_MICRO_VERSION 0 /** * This macro turns the version numbers into a numeric value. @@ -74,7 +73,7 @@ extern "C" { * \param minor the minorversion number. * \param patch the patch version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM(major, minor, patch) \ ((major) * 1000000 + (minor) * 1000 + (patch)) @@ -86,7 +85,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) @@ -97,7 +96,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) @@ -108,14 +107,16 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) /** * This is the version number macro for the current SDL version. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion */ #define SDL_VERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION) @@ -123,7 +124,7 @@ extern "C" { /** * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ (SDL_VERSION >= SDL_VERSIONNUM(X, Y, Z)) @@ -140,7 +141,7 @@ extern "C" { * * \returns the version of the linked library. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRevision */ @@ -166,7 +167,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); * \returns an arbitrary string, uniquely identifying the exact revision of * the SDL library in use. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVersion */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_video.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_video.h index 7cce828..a7afc32 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_video.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_video.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,28 @@ /** * # CategoryVideo * - * SDL video functions. + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). */ #ifndef SDL_video_h_ @@ -49,7 +70,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_DisplayID; @@ -58,7 +79,7 @@ typedef Uint32 SDL_DisplayID; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_WindowID; @@ -82,7 +103,7 @@ typedef Uint32 SDL_WindowID; /** * System theme. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemTheme { @@ -91,13 +112,21 @@ typedef enum SDL_SystemTheme SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ } SDL_SystemTheme; -/* Internal display mode data */ +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** * The structure that defines a display mode. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetFullscreenDisplayModes * \sa SDL_GetDesktopDisplayMode @@ -123,7 +152,7 @@ typedef struct SDL_DisplayMode /** * Display orientation values; the way a display is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_DisplayOrientation { @@ -137,7 +166,7 @@ typedef enum SDL_DisplayOrientation /** * The struct used as an opaque handle to a window. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateWindow */ @@ -151,7 +180,7 @@ typedef struct SDL_Window SDL_Window; * changed on existing windows by the app, and some of it might be altered by * the user or system outside of the app's control. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ @@ -185,31 +214,91 @@ typedef Uint64 SDL_WindowFlags; /** - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. * - * \since This macro is available since SDL 3.0.0. + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u + +/** + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) + +/** + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A magic value used with SDL_WINDOWPOS_CENTERED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u /** * Used to indicate that the window position should be centered. * - * \since This macro is available since SDL 3.0.0. + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. */ -#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) + +/** + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlashOperation { @@ -221,30 +310,102 @@ typedef enum SDL_FlashOperation /** * An opaque handle to an OpenGL context. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef int SDL_EGLint; /** - * EGL attribute initialization callback types. + * EGL platform attribute initialization callback. * - * \since This datatype is available since SDL 3.0.0. + * This is called when SDL is attempting to create an EGL context, to let the + * app add extra attributes to its eglGetPlatformDisplay() call. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks */ -typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); -typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); /** * An enumeration of OpenGL configuration attributes. @@ -261,9 +422,9 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); * fail if the GL can't provide your requested attributes at a minimum, but * you should check to see exactly what you got. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ -typedef enum SDL_GLattr +typedef enum SDL_GLAttr { SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ @@ -284,64 +445,64 @@ typedef enum SDL_GLattr SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ - SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ - SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLcontextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS, SDL_GL_EGL_PLATFORM -} SDL_GLattr; +} SDL_GLAttr; /** * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLprofile -{ - SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, - SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, - SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ -} SDL_GLprofile; +typedef Uint32 SDL_GLProfile; + +#define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */ +#define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */ +#define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ + /** - * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextFlag -{ - SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, - SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, - SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG = 0x0004, - SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 -} SDL_GLcontextFlag; +typedef Uint32 SDL_GLContextFlag; + +#define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001 +#define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002 +#define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004 +#define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008 + /** * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR * attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextReleaseFlag -{ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 -} SDL_GLcontextReleaseFlag; +typedef Uint32 SDL_GLContextReleaseFlag; + +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000 +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001 + /** * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLContextResetNotification -{ - SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, - SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 -} SDL_GLContextResetNotification; +typedef Uint32 SDL_GLContextResetNotification; + +#define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000 +#define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001 + /* Function prototypes */ @@ -350,7 +511,9 @@ typedef enum SDL_GLContextResetNotification * * \returns the number of built in video drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVideoDriver */ @@ -369,7 +532,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers */ @@ -385,7 +550,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); * \returns the name of the current video driver or NULL if no driver has been * initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers * \sa SDL_GetVideoDriver @@ -397,7 +564,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); * * \returns the current system theme, light, dark, or unknown. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); @@ -410,7 +579,9 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); @@ -420,7 +591,9 @@ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); * \returns the instance ID of the primary display on success or 0 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -448,7 +621,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); @@ -462,7 +637,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa * \returns the name of a display or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -471,19 +648,22 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa /** * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the usable desktop area represented by a display, in screen @@ -499,15 +679,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayI * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the orientation of a display when it is unrotated. @@ -516,7 +698,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID di * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -529,7 +713,9 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -543,12 +729,21 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays */ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID); @@ -573,7 +768,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -587,7 +784,7 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * refresh rate default to the desktop mode if they are set to 0. The modes * are scanned with size being first priority, format being second priority, * and finally checking the refresh rate. If all the available modes are too - * small, then NULL is returned. + * small, then false is returned. * * \param displayID the instance ID of the display to query. * \param w the width in pixels of the desired display mode. @@ -596,17 +793,19 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * for the desktop refresh rate. * \param include_high_density_modes boolean to include high density modes in * the search. - * \param mode a pointer filled in with the closest display mode equal to or - * larger than the desired mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closest a pointer filled in with the closest display mode equal to + * or larger than the desired mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes, SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest); /** * Get information about the desktop's display mode. @@ -620,7 +819,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Dis * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayMode * \sa SDL_GetDisplays @@ -639,7 +840,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDisplays @@ -653,7 +856,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SD * \returns the instance ID of the display containing the point or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -668,7 +873,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point * closest to the center of the rect on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -683,7 +890,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect * * on success or 0 on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -701,7 +910,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowDisplayScale */ @@ -725,7 +936,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window); * \returns the display scale, or 0.0f on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); @@ -743,24 +956,26 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * taken effect. * * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an - * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new - * mode dimensions. + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode + * dimensions. * * \param window the window to affect. * \param mode a pointer to the display mode to use, which can be NULL for * borderless fullscreen desktop mode, or one of the fullscreen * modes returned by SDL_GetFullscreenDisplayModes() to set an * exclusive fullscreen mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreen * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); /** * Query the display mode to use when a window is visible at fullscreen. @@ -769,7 +984,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *win * \returns a pointer to the exclusive fullscreen mode to use or NULL for * borderless fullscreen desktop mode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -785,7 +1002,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode( * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); @@ -797,7 +1016,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); @@ -811,7 +1032,9 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); @@ -870,7 +1093,7 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). * * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. * * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, * SDL_CreateWindow() will fail. @@ -890,8 +1113,11 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindowAndRenderer * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindowWithProperties * \sa SDL_DestroyWindow @@ -901,36 +1127,41 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int /** * Create a child popup window of the specified parent window. * - * 'flags' **must** contain exactly one of the following: - - * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any - * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu. - * The topmost popup menu will implicitly gain the keyboard focus. + * The flags parameter **must** contain at least one of the following: + * + * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any + * input events. + * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost + * popup menu will implicitly gain the keyboard focus. * * The following flags are not relevant to popup window creation and will be * ignored: * - * - 'SDL_WINDOW_MINIMIZED' - * - 'SDL_WINDOW_MAXIMIZED' - * - 'SDL_WINDOW_FULLSCREEN' - * - 'SDL_WINDOW_BORDERLESS' + * - `SDL_WINDOW_MINIMIZED` + * - `SDL_WINDOW_MAXIMIZED` + * - `SDL_WINDOW_FULLSCREEN` + * - `SDL_WINDOW_BORDERLESS` + * + * The following flags are incompatible with popup window creation and will + * cause it to fail: + * + * - `SDL_WINDOW_UTILITY` + * - `SDL_WINDOW_MODAL` * * The parent parameter **must** be non-null and a valid window. The parent of * a popup window can be either a regular, toplevel window, or another popup * window. * * Popup windows cannot be minimized, maximized, made fullscreen, raised, - * flash, be made a modal window, be the parent of a modal window, or grab the - * mouse and/or keyboard. Attempts to do so will fail. + * flash, be made a modal window, be the parent of a toplevel window, or grab + * the mouse and/or keyboard. Attempts to do so will fail. * * Popup windows implicitly do not have a border/decorations and do not appear * on the taskbar/dock or in lists of windows such as alt-tab menus. * - * If a parent window is hidden, any child popup windows will be recursively - * hidden as well. Child popup windows not explicitly hidden will be restored - * when the parent is shown. - * - * If the parent window is destroyed, any child popup windows will be - * recursively destroyed as well. + * If a parent window is hidden or destroyed, any child popup windows will be + * recursively hidden or destroyed as well. Child popup windows not explicitly + * hidden will be restored when the parent is shown. * * \param parent the parent of the window, must not be NULL. * \param offset_x the x position of the popup window relative to the origin @@ -944,7 +1175,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_CreateWindowWithProperties @@ -987,7 +1220,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used * with OpenGL rendering * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the - * parent of this window, required for windows with the "toolip", "menu", + * parent of this window, required for windows with the "tooltip", "menu", * and "modal" properties * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be * resizable @@ -1003,10 +1236,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * * These are additional supported properties on macOS: * @@ -1024,8 +1259,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * [README/wayland](README/wayland) for more information on using custom * surfaces. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the - * application wants an associated `wl_egl_window` object to be created, - * even if the window does not have the OpenGL property or flag set. + * application wants an associated `wl_egl_window` object to be created and + * attached to the window, even if the window does not have the OpenGL + * property or `SDL_WINDOW_OPENGL` flag set. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface * associated with the window, if you want to wrap an existing window. See * [README/wayland](README/wayland) for more information. @@ -1061,7 +1297,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateWindow @@ -1114,7 +1352,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFromID */ @@ -1130,7 +1370,9 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window); * \returns the window associated with `id` or NULL if it doesn't exist; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowID */ @@ -1143,7 +1385,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id); * \returns the parent of the window on success or NULL if the window has no * parent. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow */ @@ -1181,7 +1425,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)` * UIWindow associated with the window * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag - * assocated with metal views on the window + * associated with metal views on the window * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's * framebuffer object. It must be bound when rendering to the screen using * OpenGL. @@ -1206,6 +1450,11 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag * assocated with metal views on the window * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the + * associated overlay window. + * * On Vivante: * * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType @@ -1215,11 +1464,6 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with * the window * - * On UWP: - * - * - `SDL_PROP_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow - * associated with the window - * * On Windows: * * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window @@ -1237,6 +1481,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * the window * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window * associated with the window * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated @@ -1263,7 +1509,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); @@ -1283,15 +1531,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window #define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev" #define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window" #define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag" +#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id" #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" -#define SDL_PROP_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window" #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" #define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display" #define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface" +#define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport" #define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window" #define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface" #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel" @@ -1308,7 +1557,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window * \param window the window to query. * \returns a mask of the SDL_WindowFlags associated with `window`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_HideWindow @@ -1327,14 +1578,16 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * * \param window the window to change. * \param title the desired window title in UTF-8 format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowTitle */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); /** * Get the title of a window. @@ -1343,7 +1596,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, cons * \returns the title of the window in UTF-8 format or "" if there is no * title. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowTitle */ @@ -1364,23 +1619,24 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); * * \param window the window to change. * \param icon an SDL_Surface structure containing the icon for the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); /** * Request that the window's position be set. * - * If, at the time of this request, the window is in a fixed-size state such - * as maximized, this request may be deferred until the window returns to a - * resizable state. + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. * * This can be used to reposition fullscreen-desktop windows onto a different - * display, however, exclusive fullscreen windows are locked to a specific - * display and can only be repositioned programmatically via + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via * SDL_SetWindowFullscreenMode(). * * On some windowing systems this request is asynchronous and the new @@ -1401,15 +1657,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_S * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * `SDL_WINDOWPOS_UNDEFINED`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); /** * Get the position of a window. @@ -1425,24 +1683,25 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, i * NULL. * \param y a pointer filled in with the y position of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowPosition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); /** * Request that the size of a window's client area be set. * - * If, at the time of this request, the window in a fixed-size state, such as - * maximized or fullscreen, the request will be deferred until the window - * exits this state and becomes resizable again. + * If the window is in a fullscreen or maximized state, this request has no + * effect. * - * To change the fullscreen mode of a window, use - * SDL_SetWindowFullscreenMode() + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). * * On some windowing systems, this request is asynchronous and the new window * size may not have have been applied immediately upon the return of this @@ -1459,16 +1718,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, i * \param window the window to change. * \param w the width of the window, must be > 0. * \param h the height of the window, must be > 0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); /** * Get the size of a window's client area. @@ -1480,16 +1741,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w * \param window the window to query the width and height from. * \param w a pointer filled in with the width of the window, may be NULL. * \param h a pointer filled in with the height of the window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize * \sa SDL_GetWindowSizeInPixels * \sa SDL_SetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); /** * Get the safe area for this window. @@ -1497,19 +1760,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int * * Some devices have portions of the screen which are partially obscured or * not interactive, possibly due to on-screen controls, curved edges, camera * notches, TV overscan, etc. This function provides the area of the window - * which is safe to have interactible content. You should continue rendering + * which is safe to have interactable content. You should continue rendering * into the rest of the window, but it should not contain visually important * or interactible content. * * \param window the window to query. * \param rect a pointer filled in with the client area that is safe for * interactive content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); /** * Request that the aspect ratio of a window's client area be set. @@ -1540,15 +1805,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, S * limit. * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); /** * Get the size of a window's client area. @@ -1558,19 +1825,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window * window, may be NULL. * \param max_aspect a pointer filled in with the maximum aspect ratio of the * window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowAspectRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); /** * Get the size of a window's borders (decorations) around the client area. * - * Note: If this function fails (returns -1), the size values will be + * Note: If this function fails (returns false), the size values will be * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the * window in question was borderless. * @@ -1580,7 +1849,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * window has been presented and composited, so that the window system has a * chance to decorate the window and provide the border dimensions to SDL. * - * This function also returns -1 if getting the information is not supported. + * This function also returns false if getting the information is not + * supported. * * \param window the window to query the size values of the border * (decorations) from. @@ -1592,14 +1862,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; * NULL is permitted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); /** * Get the size of a window's client area, in pixels. @@ -1609,15 +1881,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window * NULL. * \param h a pointer to variable for storing the height in pixels, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); /** * Set the minimum size of a window's client area. @@ -1625,15 +1899,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *windo * \param window the window to change. * \param min_w the minimum width of the window, or 0 for no limit. * \param min_h the minimum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); /** * Get the minimum size of a window's client area. @@ -1643,15 +1919,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the minimum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); /** * Set the maximum size of a window's client area. @@ -1659,15 +1937,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window * \param window the window to change. * \param max_w the maximum width of the window, or 0 for no limit. * \param max_h the maximum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); /** * Get the maximum size of a window's client area. @@ -1677,15 +1957,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the maximum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); /** * Set the border state of a window. @@ -1697,15 +1979,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window * You can't change the border state of a fullscreen window. * * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bool bordered); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); /** * Set the user-resizable state of a window. @@ -1717,15 +2001,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, S * You can't change the resizable state of a fullscreen window. * * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_bool resizable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); /** * Set the window to always be above the others. @@ -1734,43 +2020,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, * will bring the window to the front and keep the window above the rest. * * \param window the window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param on_top true to set the window always on top, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL_bool on_top); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); /** * Show a window. * * \param window the window to show. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); /** * Hide a window. * * \param window the window to hide. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); /** * Request that a window be raised above other windows and gain the input @@ -1783,12 +2075,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); /** * Request that the window be made as large as possible. @@ -1811,22 +2105,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); * and Wayland window managers may vary. * * \param window the window to maximize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MinimizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); /** * Request that the window be minimized to an iconic representation. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window - * state may not have have been applied immediately upon the return of this + * state may not have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to * block until the changes have taken effect. * @@ -1835,21 +2134,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to minimize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); /** * Request that the size and position of a minimized or maximized window be * restored. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1860,16 +2164,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to restore. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_MinimizeWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); /** * Request that the window's fullscreen state be changed. @@ -1888,18 +2194,20 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); * is just a request, it can be denied by the windowing system. * * \param window the window to change. - * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed - * mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); /** * Block until any pending window state is finalized. @@ -1915,10 +2223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * * \param window the window for which to wait for the pending state to be * applied. - * \returns SDL_TRUE on success or SDL_FALSE if the operation timed out before - * the window was in the requested state. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSize * \sa SDL_SetWindowPosition @@ -1928,20 +2238,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * \sa SDL_RestoreWindow * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SyncWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); /** * Return whether the window has a surface associated with it. * * \param window the window to query. - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. + * \returns true if there is a surface associated with the window, or false + * otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); /** * Get the SDL surface associated with the window. @@ -1961,7 +2273,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyWindowSurface * \sa SDL_WindowHasSurface @@ -1985,14 +2299,16 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * * \param window the window. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) @@ -2003,14 +2319,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *windo * \param window the window to query. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetWindowSurfaceVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); /** * Copy the window surface to the screen. @@ -2021,15 +2339,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *windo * This function is equivalent to the SDL 1.2 API SDL_Flip(). * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); /** * Copy areas of the window surface to the screen. @@ -2048,29 +2368,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window) * \param rects an array of SDL_Rect structures representing areas of the * surface to copy, in pixels. * \param numrects the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); /** * Destroy the surface associated with the window. * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); /** * Set a window's keyboard grab mode. @@ -2092,16 +2416,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window * other window loses its grab in favor of the caller's window. * * \param window the window for which the keyboard grab mode should be set. - * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab keyboard, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); /** * Set a window's mouse grab mode. @@ -2109,47 +2435,60 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *windo * Mouse grab confines the mouse cursor to the window. * * \param window the window for which the mouse grab mode should be set. - * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab mouse, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * - * \sa SDL_GetWindowMouseGrab + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); /** * Get a window's keyboard grab mode. * * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \returns true if keyboard is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); /** * Get a window's mouse grab mode. * * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \returns true if mouse is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); /** * Get the window that currently has an input grab enabled. * * \returns the window if input is grabbed or NULL otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab @@ -2165,15 +2504,18 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \param window the window that will be associated with the barrier. * \param rect a rectangle area in window-relative coordinates. If NULL the * barrier for the specified window will be destroyed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); /** * Get the mouse confinement rectangle of a window. @@ -2182,9 +2524,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, * \returns a pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab */ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window); @@ -2194,18 +2540,20 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * * The parameter `opacity` will be clamped internally between 0.0f * (transparent) and 1.0f (opaque). * - * This function also returns -1 if setting the opacity isn't supported. + * This function also returns false if setting the opacity isn't supported. * * \param window the window which will be made transparent or opaque. * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowOpacity */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); /** * Get the opacity of a window. @@ -2217,43 +2565,81 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, fl * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowOpacity */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); /** - * Set the window as a modal to a parent window. + * Set the window as a child of a parent window. * - * If the window is already modal to an existing window, it will be reparented - * to the new owner. Setting the parent window to null unparents the modal - * window and removes modal status. + * If the window is already the child of an existing window, it will be + * reparented to the new owner. Setting the parent window to NULL unparents + * the window and removes child window status. * - * Setting a window as modal to a parent that is a descendent of the modal - * window results in undefined behavior. + * If a parent window is hidden or destroyed, the operation will be + * recursively applied to child windows. Child windows hidden with the parent + * that did not have their hidden status explicitly set will be restored when + * the parent is shown. * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModal() to cancel the modal status before + * attempting to change the parent. * - * \since This function is available since SDL 3.0.0. + * Popup windows cannot change parents and attempts to do so will fail. + * + * Setting a parent window that is currently the sibling or descendent of the + * child window results in undefined behavior. + * + * \param window the window that should become the child of a parent. + * \param parent the new parent window for the child window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowModal */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window, SDL_Window *parent_window); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); /** * Set whether the window may have input focus. * * \param window the window to set focusable state. - * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow - * input focus. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param focusable true to allow input focus, false to not allow input focus. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_bool focusable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); /** @@ -2272,17 +2658,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, * the client area. * \param y the y coordinate of the menu, relative to the origin (top-left) of * the client area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); /** * Possible return values from the SDL_HitTest callback. * - * \since This enum is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This enum is available since SDL 3.2.0. * * \sa SDL_HitTest */ @@ -2335,7 +2725,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * Specifying NULL for a callback disables hit-testing. Hit-testing is * disabled by default. * - * Platforms that don't support this functionality will return SDL_FALSE + * Platforms that don't support this functionality will return false * unconditionally, even if you're attempting to disable hit-testing. * * Your callback may fire at any time, and its firing does not indicate any @@ -2349,58 +2739,72 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \param window the window to set hit-testing on. * \param callback the function to call when doing a hit-test. * \param callback_data an app-defined void pointer passed to **callback**. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); /** * Set the shape of a transparent window. * * This sets the alpha channel of a transparent window and any fully * transparent areas are also transparent to mouse clicks. If you are using - * something besides the SDL render API, then you are responsible for setting - * the alpha channel of the window yourself. + * something besides the SDL render API, then you are responsible for drawing + * the alpha channel of the window to match the shape alpha channel to get + * consistent cross-platform results. * * The shape is copied inside this function, so you can free it afterwards. If * your shape surface changes, you should call SDL_SetWindowShape() again to - * update the window. + * update the window. This is an expensive operation, so should be done + * sparingly. * * The window must have been created with the SDL_WINDOW_TRANSPARENT flag. * * \param window the window. * \param shape the surface representing the shape of the window, or NULL to * remove any current shape. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); /** * Request a window to demand attention from the user. * * \param window the window to be flashed. * \param operation the operation to perform. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); /** * Destroy a window. * - * Any popups or modal windows owned by the window will be recursively - * destroyed as well. + * Any child windows owned by the window will be recursively destroyed as + * well. + * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. * * \param window the window to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindow @@ -2416,28 +2820,31 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. + * \returns true if the screensaver is enabled, false if it is disabled. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenSaverEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); /** * Allow the screen to be blanked by a screen saver. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); /** * Prevent the screen from being blanked by a screen saver. @@ -2448,15 +2855,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); * The screensaver is disabled by default, but this may by changed by * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); /** @@ -2476,15 +2885,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); * * \param path the platform dependent OpenGL library name, or NULL to open the * default OpenGL library. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); /** * Get an OpenGL function by name. @@ -2531,7 +2942,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); * \returns a pointer to the named OpenGL function. The returned pointer * should be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ExtensionSupported * \sa SDL_GL_LoadLibrary @@ -2550,7 +2963,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char * \returns a pointer to the named EGL function. The returned pointer should * be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EGL_GetCurrentDisplay */ @@ -2559,7 +2974,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha /** * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_LoadLibrary */ @@ -2580,16 +2997,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * every time you need to know. * * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * \returns true if the extension is supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** * Reset all previously set OpenGL context attributes to their default values. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute @@ -2604,34 +3025,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * SDL_GL_GetAttribute() to check the values after creating the OpenGL * context, since the values obtained can differ from the requested ones. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * set. * \param value the desired value for the attribute. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * get. * \param value a pointer filled in with the current value of `attr`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value); /** * Create an OpenGL context for an OpenGL window, and make it current. @@ -2648,7 +3073,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *v * \returns the OpenGL context associated with `window` or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_DestroyContext * \sa SDL_GL_MakeCurrent @@ -2662,14 +3089,16 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * * \param window the window to associate with the context. * \param context the OpenGL context to associate with the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); /** * Get the currently active OpenGL window. @@ -2677,7 +3106,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_ * \returns the currently active OpenGL window on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); @@ -2687,7 +3118,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); * \returns the currently active OpenGL context or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_MakeCurrent */ @@ -2699,7 +3132,9 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * \returns the currently active EGL display or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); @@ -2709,7 +3144,9 @@ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); * \returns the currently active EGL config or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); @@ -2720,7 +3157,9 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); * \returns the EGLSurface pointer associated with the window, or NULL on * failure. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); @@ -2728,27 +3167,25 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * Sets the callbacks for defining custom EGLAttrib arrays for EGL * initialization. * - * Each callback should return a pointer to an EGL attribute array terminated - * with EGL_NONE. Callbacks may return NULL pointers to signal an error, which - * will cause the SDL_CreateWindow process to fail gracefully. - * - * The arrays returned by each callback will be appended to the existing - * attribute arrays defined by SDL. + * Callbacks that aren't needed can be set to NULL. * * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. * * \param platformAttribCallback callback for attributes to pass to - * eglGetPlatformDisplay. + * eglGetPlatformDisplay. May be NULL. * \param surfaceAttribCallback callback for attributes to pass to - * eglCreateSurface. + * eglCreateSurface. May be NULL. * \param contextAttribCallback callback for attributes to pass to - * eglCreateContext. + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, - SDL_EGLIntArrayCallback surfaceAttribCallback, - SDL_EGLIntArrayCallback contextAttribCallback); + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); /** * Set the swap interval for the current OpenGL context. @@ -2758,7 +3195,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * the vertical retrace for a given frame, it swaps buffers immediately, which * might be less jarring for the user during occasional framerate drops. If an * application requests adaptive vsync and the system does not support it, - * this function will fail and return SDL_FALSE. In such a case, you should + * this function will fail and return false. In such a case, you should * probably retry the call with 1 for the interval. * * Adaptive vsync is implemented for some glX drivers with @@ -2770,14 +3207,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * * \param interval 0 for immediate updates, 1 for updates synchronized with * the vertical retrace, -1 for adaptive vsync. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); /** * Get the swap interval for the current OpenGL context. @@ -2789,14 +3228,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); * synchronization, 1 if the buffer swap is synchronized with * the vertical retrace, and -1 if late swaps happen * immediately instead of waiting for the next retrace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_SetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); /** * Update a window with OpenGL rendering. @@ -2809,25 +3250,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); * extra. * * \param window the window to change. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); /** * Delete an OpenGL context. * * \param context the OpenGL context to be deleted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); /* @} *//* OpenGL support functions */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_vulkan.h b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_vulkan.h index c31d33c..5a48756 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_vulkan.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Headers/SDL_vulkan.h @@ -23,11 +23,25 @@ * # CategoryVulkan * * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. */ #ifndef SDL_vulkan_h_ #define SDL_vulkan_h_ +#include #include #include @@ -55,6 +69,10 @@ VK_DEFINE_HANDLE(VkPhysicalDevice) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) struct VkAllocationCallbacks; +/* Make sure to undef to avoid issues in case of later vulkan include */ +#undef VK_DEFINE_HANDLE +#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE + #endif /* !NO_SDL_VULKAN_TYPEDEFS */ /** @@ -69,6 +87,13 @@ struct VkAllocationCallbacks; * creating any Vulkan windows. If no Vulkan loader library is loaded, the * default library will be loaded upon creation of the first Vulkan window. * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * * It is fairly common for Vulkan applications to link with libvulkan instead * of explicitly loading it at run time. This will work with SDL provided the * application links to a dynamic library and both it and SDL use the same @@ -95,15 +120,17 @@ struct VkAllocationCallbacks; * library version. * * \param path the platform dependent Vulkan loader library name or NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); /** * Get the address of the `vkGetInstanceProcAddr` function. @@ -122,14 +149,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); /** * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_LoadLibrary */ @@ -153,7 +193,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * \returns an array of extension name strings on success, NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_CreateSurface */ @@ -175,15 +215,15 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension * allocator that creates the surface. Can be NULL. * \param surface a pointer to a VkSurfaceKHR handle to output the newly * created surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_DestroySurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, const struct VkAllocationCallbacks *allocator, VkSurfaceKHR* surface); @@ -206,7 +246,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window * \param allocator a VkAllocationCallbacks struct, which lets the app set the * allocator that destroys the surface. Can be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_CreateSurface @@ -226,14 +266,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, * \param physicalDevice a valid Vulkan physical device handle. * \param queueFamilyIndex a valid queue family index for the given physical * device. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error - * occurred. + * \returns true if supported, false if unsupported or an error occurred. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/INSTALL.md b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/INSTALL.md new file mode 100644 index 0000000..97e4ab6 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/INSTALL.md @@ -0,0 +1,41 @@ + +# Using this package + +This package contains SDL built for Xcode. + +To use this package in Xcode, drag `SDL3.framework` into your project. + +# Documentation + +An API reference, tutorials, and additional documentation is available at: + +https://wiki.libsdl.org/SDL3 + +# Example code + +There are simple example programs available at: + +https://examples.libsdl.org/SDL3 + +# Discussions + +## Discord + +You can join the official Discord server at: + +https://discord.com/invite/BwpFGBWsv8 + +## Forums/mailing lists + +You can join SDL development discussions at: + +https://discourse.libsdl.org/ + +Once you sign up, you can use the forum through the website or as a mailing list from your email client. + +## Announcement list + +You can sign up for the low traffic announcement list at: + +https://www.libsdl.org/mailing-list.php + diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Info.plist b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Info.plist index 1993298..d1bf89c 100644 Binary files a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Info.plist and b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/Info.plist differ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/License.txt b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/License.txt index 42f3736..23abb73 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/License.txt +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/License.txt @@ -1,6 +1,4 @@ - -Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -17,3 +15,4 @@ freely, subject to the following restrictions: 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. + diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/README.md b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/README.md new file mode 100644 index 0000000..68b0923 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/README.md @@ -0,0 +1,17 @@ + +Simple DirectMedia Layer (SDL for short) is a cross-platform library +designed to make it easy to write multi-media software, such as games +and emulators. + +You can find the latest release and additional information at: +https://www.libsdl.org/ + +Installation instructions and a quick introduction is available in +[INSTALL.md](INSTALL.md) + +This library is distributed under the terms of the zlib license, +available in [LICENSE.txt](LICENSE.txt). + +Enjoy! + +Sam Lantinga (slouken@libsdl.org) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/ReadMe.txt b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/ReadMe.txt deleted file mode 100644 index 6ea9347..0000000 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/ReadMe.txt +++ /dev/null @@ -1,44 +0,0 @@ -The Simple DirectMedia Layer (SDL for short) is a cross-platform -library designed to make it easy to write multi-media software, -such as games and emulators. - -The Simple DirectMedia Layer library source code is available from: -http://www.libsdl.org/ - -This library is distributed under the terms of the zlib license: -http://zlib.net/zlib_license.html - - -This packages contains the SDL framework for macOS. -Conforming with Apple guidelines, this framework -contains both the SDL runtime component and development header files. - - -To Install: -Copy "SDL3.xcframework" and "share" to /Library/Frameworks - -You may alternatively install it in /Library/Frameworks -if your access privileges are not high enough. - - -Use in CMake projects: -SDL3.xcframework can be used in CMake projects using the following pattern: -```cmake -find_package(SDL3 REQUIRED COMPONENTS SDL3) -add_executable(my_game ${MY_SOURCES}) -target_link_libraries(my_game PRIVATE SDL3::SDL3) -``` -If SDL3.framework is installed in a non-standard location, -please refer to the following link for ways to configure CMake: -https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure - - -Additional References: - - - Screencast tutorials for getting started with OpenSceneGraph/macOS are - available at: - http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips - Though these are OpenSceneGraph centric, the same exact concepts apply to - SDL, thus the videos are recommended for everybody getting started with - developing on macOS. (You can skim over the PlugIns stuff since SDL - doesn't have any PlugIns to worry about.) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/SDL3 b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/SDL3 index c86dcae..fef318a 100755 Binary files a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/SDL3 and b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/SDL3 differ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/compile_shaders.sh b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/compile_shaders.sh deleted file mode 100755 index ef5e744..0000000 --- a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/compile_shaders.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/bin/bash - -set -x -set -e -cd `dirname "$0"` - -shadernames=(FullscreenVert BlitFrom2D BlitFrom2DArray BlitFrom3D BlitFromCube) - -generate_shaders() -{ - fileplatform=$1 - compileplatform=$2 - sdkplatform=$3 - minversion=$4 - - for shadername in "${shadernames[@]}"; do - xcrun -sdk $sdkplatform metal -c -std=$compileplatform-metal1.1 -m$sdkplatform-version-min=$minversion -Wall -O3 -D COMPILE_$shadername -o ./$shadername.air ./Metal_Blit.metal || exit $? - xcrun -sdk $sdkplatform metallib -o $shadername.metallib $shadername.air || exit $? - xxd -i $shadername.metallib | perl -w -p -e 's/\Aunsigned /const unsigned /;' >./${shadername}_$fileplatform.h - rm -f $shadername.air $shadername.metallib - done -} - -generate_shaders macos macos macosx 10.11 -generate_shaders ios ios iphoneos 8.0 -generate_shaders iphonesimulator ios iphonesimulator 8.0 -generate_shaders tvos ios appletvos 9.0 -generate_shaders tvsimulator ios appletvsimulator 9.0 - -# Bundle together one mega-header -catShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - cat ${shadername}_$target.h >> Metal_Blit.h - done -} - -rm -f Metal_Blit.h -echo "#if defined(SDL_PLATFORM_IOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders iphonesimulator - echo "#else" >> Metal_Blit.h - catShaders ios - echo "#endif" >> Metal_Blit.h -echo "#elif defined(SDL_PLATFORM_TVOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders tvsimulator - echo "#else" >> Metal_Blit.h - catShaders tvos - echo "#endif" >> Metal_Blit.h -echo "#else" >> Metal_Blit.h - catShaders macos -echo "#endif" >> Metal_Blit.h - -# Clean up -cleanupShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - rm -f ${shadername}_$target.h - done -} -cleanupShaders iphonesimulator -cleanupShaders ios -cleanupShaders tvsimulator -cleanupShaders tvos -cleanupShaders macos \ No newline at end of file diff --git a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/default.metallib b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/default.metallib index 4115aa3..7742f24 100644 Binary files a/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/default.metallib and b/Frameworks/SDL3.xcframework/tvos-arm64/SDL3.framework/default.metallib differ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3Config.cmake b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3Config.cmake new file mode 100644 index 0000000..03673f3 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3Config.cmake @@ -0,0 +1,106 @@ +# SDL3 CMake configuration file: +# This file is meant to be placed in Resources/CMake of a SDL3 framework + +# INTERFACE_LINK_OPTIONS needs CMake 3.12 +cmake_minimum_required(VERSION 3.12) + +include(FeatureSummary) +set_package_properties(SDL3 PROPERTIES + URL "https://www.libsdl.org/" + DESCRIPTION "low level access to audio, keyboard, mouse, joystick, and graphics hardware" +) + +# Copied from `configure_package_config_file` +macro(set_and_check _var _file) + set(${_var} "${_file}") + if(NOT EXISTS "${_file}") + message(FATAL_ERROR "File or directory ${_file} referenced by variable ${_var} does not exist !") + endif() +endmacro() + +# Copied from `configure_package_config_file` +macro(check_required_components _NAME) + foreach(comp ${${_NAME}_FIND_COMPONENTS}) + if(NOT ${_NAME}_${comp}_FOUND) + if(${_NAME}_FIND_REQUIRED_${comp}) + set(${_NAME}_FOUND FALSE) + endif() + endif() + endforeach() +endmacro() + +set(SDL3_FOUND TRUE) + +# Compute the installation prefix relative to this file. +set(_sdl3_framework_path "${CMAKE_CURRENT_LIST_DIR}") # > /SDL3.framework/Resources/CMake/ +get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" REALPATH) # > /SDL3.framework/Versions/Current/Resources/CMake +get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" REALPATH) # > /SDL3.framework/Versions/A/Resources/CMake/ +get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/Versions/A/Resources/ +get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/Versions/A/ +get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/Versions/ +get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/ +get_filename_component(_sdl3_framework_parent_path "${_sdl3_framework_path}" PATH) # > / + + +# All targets are created, even when some might not be requested though COMPONENTS. +# This is done for compatibility with CMake generated SDL3-target.cmake files. + +if(NOT TARGET SDL3::Headers) + add_library(SDL3::Headers INTERFACE IMPORTED) + set_target_properties(SDL3::Headers + PROPERTIES + INTERFACE_COMPILE_OPTIONS "SHELL:-F \"${_sdl3_framework_parent_path}\"" + ) +endif() +set(SDL3_Headers_FOUND TRUE) + +if(NOT TARGET SDL3::SDL3-shared) + add_library(SDL3::SDL3-shared SHARED IMPORTED) + set_target_properties(SDL3::SDL3-shared + PROPERTIES + FRAMEWORK "TRUE" + IMPORTED_LOCATION "${_sdl3_framework_path}" + INTERFACE_LINK_LIBRARIES "SDL3::Headers" + COMPATIBLE_INTERFACE_BOOL "SDL3_SHARED" + INTERFACE_SDL3_SHARED "ON" + COMPATIBLE_INTERFACE_STRING "SDL_VERSION" + INTERFACE_SDL_VERSION "SDL3" + ) +endif() +set(SDL3_SDL3-shared_FOUND TRUE) + +set(SDL3_SDL3-static FALSE) + +set(SDL3_SDL3_test FALSE) + +unset(_sdl3_framework_parent_path) +unset(_sdl3_framework_path) + +if(SDL3_SDL3-shared_FOUND) + set(SDL3_SDL3_FOUND TRUE) +endif() + +function(_sdl_create_target_alias_compat NEW_TARGET TARGET) + if(CMAKE_VERSION VERSION_LESS "3.18") + # Aliasing local targets is not supported on CMake < 3.18, so make it global. + add_library(${NEW_TARGET} INTERFACE IMPORTED) + set_target_properties(${NEW_TARGET} PROPERTIES INTERFACE_LINK_LIBRARIES "${TARGET}") + else() + add_library(${NEW_TARGET} ALIAS ${TARGET}) + endif() +endfunction() + +# Make sure SDL3::SDL3 always exists +if(NOT TARGET SDL3::SDL3) + if(TARGET SDL3::SDL3-shared) + _sdl_create_target_alias_compat(SDL3::SDL3 SDL3::SDL3-shared) + endif() +endif() + +check_required_components(SDL3) + +set(SDL3_LIBRARIES SDL3::SDL3) +set(SDL3_STATIC_LIBRARIES SDL3::SDL3-static) +set(SDL3_STATIC_PRIVATE_LIBS) + +set(SDL3TEST_LIBRARY SDL3::SDL3_test) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config-version.cmake b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3ConfigVersion.cmake similarity index 100% rename from Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config-version.cmake rename to Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/SDL3ConfigVersion.cmake diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config.cmake b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config.cmake deleted file mode 100644 index 784d27d..0000000 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/CMake/sdl3-config.cmake +++ /dev/null @@ -1,106 +0,0 @@ -# SDL3 CMake configuration file: -# This file is meant to be placed in Resources/CMake of a SDL3 framework - -# INTERFACE_LINK_OPTIONS needs CMake 3.12 -cmake_minimum_required(VERSION 3.12) - -include(FeatureSummary) -set_package_properties(SDL3 PROPERTIES - URL "https://www.libsdl.org/" - DESCRIPTION "low level access to audio, keyboard, mouse, joystick, and graphics hardware" -) - -# Copied from `configure_package_config_file` -macro(set_and_check _var _file) - set(${_var} "${_file}") - if(NOT EXISTS "${_file}") - message(FATAL_ERROR "File or directory ${_file} referenced by variable ${_var} does not exist !") - endif() -endmacro() - -# Copied from `configure_package_config_file` -macro(check_required_components _NAME) - foreach(comp ${${_NAME}_FIND_COMPONENTS}) - if(NOT ${_NAME}_${comp}_FOUND) - if(${_NAME}_FIND_REQUIRED_${comp}) - set(${_NAME}_FOUND FALSE) - endif() - endif() - endforeach() -endmacro() - -set(SDL3_FOUND TRUE) - -# Compute the installation prefix relative to this file. -set(_sdl3_framework_path "${CMAKE_CURRENT_LIST_DIR}") # > /SDL3.framework/Resources/CMake/ -get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" REALPATH) # > /SDL3.framework/Versions/Current/Resources/CMake -get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" REALPATH) # > /SDL3.framework/Versions/A/Resources/CMake/ -get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/Versions/A/Resources/ -get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/Versions/A/ -get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/Versions/ -get_filename_component(_sdl3_framework_path "${_sdl3_framework_path}" PATH) # > /SDL3.framework/ -get_filename_component(_sdl3_framework_parent_path "${_sdl3_framework_path}" PATH) # > / - - -# All targets are created, even when some might not be requested though COMPONENTS. -# This is done for compatibility with CMake generated SDL3-target.cmake files. - -if(NOT TARGET SDL3::Headers) - add_library(SDL3::Headers INTERFACE IMPORTED) - set_target_properties(SDL3::Headers - PROPERTIES - INTERFACE_COMPILE_OPTIONS "SHELL:-F \"${_sdl3_framework_parent_path}\"" - ) -endif() -set(SDL3_Headers_FOUND TRUE) - -if(NOT TARGET SDL3::SDL3-shared) - add_library(SDL3::SDL3-shared SHARED IMPORTED) - set_target_properties(SDL3::SDL3-shared - PROPERTIES - FRAMEWORK "TRUE" - IMPORTED_LOCATION "${_sdl3_framework_path}/SDL3" - INTERFACE_LINK_LIBRARIES "SDL3::Headers" - COMPATIBLE_INTERFACE_BOOL "SDL3_SHARED" - INTERFACE_SDL3_SHARED "ON" - COMPATIBLE_INTERFACE_STRING "SDL_VERSION" - INTERFACE_SDL_VERSION "SDL3" - ) -endif() -set(SDL3_SDL3-shared_FOUND TRUE) - -set(SDL3_SDL3-static FALSE) - -set(SDL3_SDL3_test FALSE) - -unset(_sdl3_framework_parent_path) -unset(_sdl3_framework_path) - -if(SDL3_SDL3-shared_FOUND) - set(SDL3_SDL3_FOUND TRUE) -endif() - -function(_sdl_create_target_alias_compat NEW_TARGET TARGET) - if(CMAKE_VERSION VERSION_LESS "3.18") - # Aliasing local targets is not supported on CMake < 3.18, so make it global. - add_library(${NEW_TARGET} INTERFACE IMPORTED) - set_target_properties(${NEW_TARGET} PROPERTIES INTERFACE_LINK_LIBRARIES "${TARGET}") - else() - add_library(${NEW_TARGET} ALIAS ${TARGET}) - endif() -endfunction() - -# Make sure SDL3::SDL3 always exists -if(NOT TARGET SDL3::SDL3) - if(TARGET SDL3::SDL3-shared) - _sdl_create_target_alias_compat(SDL3::SDL3 SDL3::SDL3-shared) - endif() -endif() - -check_required_components(SDL3) - -set(SDL3_LIBRARIES SDL3::SDL3) -set(SDL3_STATIC_LIBRARIES SDL3::SDL3-static) -set(SDL3_STATIC_PRIVATE_LIBS) - -set(SDL3TEST_LIBRARY SDL3::SDL3_test) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h index c963394..861c404 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -20,9 +20,12 @@ */ /** - * \file SDL.h + * Main include header for the SDL library, version 3.2.0 * - * Main include header for the SDL library, version 3.1.2 + * It is almost always best to include just this one header instead of + * picking out individual headers included here. There are exceptions to + * this rule--SDL_main.h is special and not included here--but usually + * letting SDL.h include the kitchen sink for you is the correct approach. */ #ifndef SDL_h_ @@ -30,6 +33,7 @@ #include #include +#include #include #include #include @@ -65,6 +69,7 @@ #include #include #include +#include #include #include #include @@ -76,6 +81,7 @@ #include #include #include +#include #include #include #include diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h index f5f798e..09b3b47 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_assert.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,9 +51,14 @@ * - It provides statistics and data on all failed assertions to the app. * - It allows the default assertion handler to be controlled with environment * variables, in case an automated script needs to control it. + * - It can be used as an aid to Clang's static analysis; it will treat SDL + * assertions as universally true (under the assumption that you are serious + * about the asserted claims and that your debug builds will detect when + * these claims were wrong). This can help the analyzer avoid false + * positives. * - * To use it: do a debug build and just sprinkle around tests to check your - * code! + * To use it: compile a debug build and just sprinkle around tests to check + * your code! */ #ifndef SDL_assert_h_ @@ -84,7 +89,7 @@ extern "C" { * - 3: Paranoid settings: All SDL assertion macros enabled, including * SDL_assert_paranoid. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ASSERT_LEVEL SomeNumberBasedOnVariousFactors @@ -113,24 +118,27 @@ extern "C" { * * If the program is not running under a debugger, SDL_TriggerBreakpoint will * likely terminate the app, possibly without warning. If the current platform - * isn't supported (SDL doesn't know how to trigger a breakpoint), this macro - * does nothing. + * isn't supported, this macro is left undefined. * - * \threadsafety It is safe to call this function from any thread. + * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner -#elif defined(_MSC_VER) +#elif 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) #include #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__)) #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" ) #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv) @@ -147,18 +155,40 @@ extern "C" { #include #define SDL_TriggerBreakpoint() raise(SIGTRAP) #else - /* How do we trigger breakpoints on this platform? */ - #define SDL_TriggerBreakpoint() + /* SDL_TriggerBreakpoint is intentionally left undefined on unknown platforms. */ #endif -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FUNCTION __FUNCTION__ + +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ # define SDL_FUNCTION __func__ #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) # define SDL_FUNCTION __FUNCTION__ #else # define SDL_FUNCTION "???" #endif + +/** + * A macro that reports the current file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FILE __FILE__ + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_LINE __LINE__ /* @@ -176,14 +206,50 @@ This also solves the problem of... disable assertions. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro for wrapping code in `do {} while (0);` without compiler warnings. + * + * Visual Studio with really aggressive warnings enabled needs this to avoid + * compiler complaints. + * + * the `do {} while (0);` trick is useful for wrapping code in a macro that + * may or may not be a single statement, to avoid various C language + * accidents. + * + * To use: + * + * ```c + * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0)); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NULL_WHILE_LOOP_CONDITION (0) + +#elif defined(_MSC_VER) /* Avoid /W4 warnings. */ /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking this condition isn't constant. And looks like an owl's face! */ -#ifdef _MSC_VER /* stupid /W4 warnings. */ #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) #else #define SDL_NULL_WHILE_LOOP_CONDITION (0) #endif +/** + * The macro used when an assertion is disabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is disabled (perhaps in a release build). + * + * The code does nothing, but wraps `condition` in a sizeof operator, which + * generates no code and has no side effects, but avoid compiler warnings + * about unused variables. + * + * \param condition the condition to assert (but not actually run here). + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -198,7 +264,7 @@ disable assertions. * condition, try to break in a debugger, kill the program, or ignore the * problem). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AssertState { @@ -216,11 +282,11 @@ typedef enum SDL_AssertState * used by the assertion handler, then added to the assertion report. This is * returned as a linked list from SDL_GetAssertionReport(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AssertData { - SDL_bool always_ignore; /**< SDL_TRUE if app should always continue when assertion is triggered. */ + bool always_ignore; /**< true if app should always continue when assertion is triggered. */ unsigned int trigger_count; /**< Number of times this assertion has been triggered. */ const char *condition; /**< A string of this assert's test code. */ const char *filename; /**< The source file where this assert lives. */ @@ -232,7 +298,7 @@ typedef struct SDL_AssertData /** * Never call this directly. * - * Use the SDL_assert* macros instead. + * Use the SDL_assert macros instead. * * \param data assert data structure. * \param func function name. @@ -240,29 +306,57 @@ typedef struct SDL_AssertData * \param line line number. * \returns assert state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data, const char *func, const char *file, int line) SDL_ANALYZER_NORETURN; -/* Define the trigger breakpoint call used in asserts */ -#ifndef SDL_AssertBreakpoint -#if defined(ANDROID) && defined(assert) -/* Define this as empty in case assert() is defined as SDL_assert */ -#define SDL_AssertBreakpoint() -#else + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The macro used when an assertion triggers a breakpoint. + * + * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint + * instead. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() -#endif + +#elif !defined(SDL_AssertBreakpoint) +# if defined(ANDROID) && defined(assert) + /* Define this as empty in case assert() is defined as SDL_assert */ +# define SDL_AssertBreakpoint() +# else +# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() +# endif #endif /* !SDL_AssertBreakpoint */ -/* the do {} while(0) avoids dangling else problems: - if (x) SDL_assert(y); else blah(); - ... without the do/while, the "else" could attach to this macro's "if". - We try to handle just the minimum we need here in a macro...the loop, - the static vars, and break points. The heavy lifting is handled in - SDL_ReportAssertion(), in SDL_assert.c. -*/ +/** + * The macro used when an assertion is enabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is enabled. + * + * The `do {} while(0)` avoids dangling else problems: + * + * ```c + * if (x) SDL_assert(y); else blah(); + * ``` + * + * ... without the do/while, the "else" could attach to this macro's "if". We + * try to handle just the minimum we need here in a macro...the loop, the + * static vars, and break points. The heavy lifting is handled in + * SDL_ReportAssertion(). + * + * \param condition the condition to assert. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ @@ -305,7 +399,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; } @@ -336,7 +432,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_release(condition) SDL_disabled_assert(condition) @@ -363,7 +461,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_paranoid(condition) SDL_disabled_assert(condition) @@ -389,7 +489,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * #endif /** - * An assertion test that always performed. + * An assertion test that is always performed. * * This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You * almost never want to use this, as it could trigger on an end-user's system, @@ -405,7 +505,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * * \param condition boolean value to test. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_assert_always(condition) SDL_enabled_assert(condition) @@ -418,7 +520,10 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * * \param userdata what was passed as `userdata` to SDL_SetAssertionHandler(). * \returns an SDL_AssertState value indicating how to handle the failure. * - * \since This datatype is available since SDL 3.0.0. + * \threadsafety This callback may be called from any thread that triggers an + * assert at any time. + * + * \since This datatype is available since SDL 3.2.0. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( const SDL_AssertData *data, void *userdata); @@ -440,7 +545,9 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( * fails or NULL for the default handler. * \param userdata a pointer that is passed to `handler`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -459,7 +566,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler( * \returns the default SDL_AssertionHandler that is called when an assert * triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionHandler */ @@ -482,7 +591,9 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler( * was passed to SDL_SetAssertionHandler(). * \returns the SDL_AssertionHandler that is called when an assert triggers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAssertionHandler */ @@ -508,9 +619,15 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void ** * ``` * * \returns a list of all failed assertions or NULL if the list is empty. This - * memory should not be modified or freed by the application. + * memory should not be modified or freed by the application. This + * pointer remains valid until the next call to SDL_Quit() or + * SDL_ResetAssertionReport(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads calling + * SDL_ResetAssertionReport() simultaneously, may render the + * returned pointer invalid. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetAssertionReport */ @@ -524,7 +641,11 @@ extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void); * no items. In addition, any previously-triggered assertions will be reset to * a trigger_count of zero, and their always_ignore state will be false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. Other threads triggering an + * assertion, or simultaneously calling this function may cause + * memory leaks or crashes. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAssertionReport */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_asyncio.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_asyncio.h new file mode 100644 index 0000000..b36cb07 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_asyncio.h @@ -0,0 +1,546 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/* WIKI CATEGORY: AsyncIO */ + +/** + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + */ + +#ifndef SDL_asyncio_h_ +#define SDL_asyncio_h_ + +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + */ +typedef struct SDL_AsyncIO SDL_AsyncIO; + +/** + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOTaskType +{ + SDL_ASYNCIO_TASK_READ, /**< A read operation. */ + SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */ + SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */ +} SDL_AsyncIOTaskType; + +/** + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_AsyncIOResult +{ + SDL_ASYNCIO_COMPLETE, /**< request was completed without error */ + SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */ + SDL_ASYNCIO_CANCELED /**< request was canceled before completing. */ +} SDL_AsyncIOResult; + +/** + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_AsyncIOOutcome +{ + SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */ + SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */ + SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */ + void *buffer; /**< buffer where data was read/written. */ + Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */ + Uint64 bytes_requested; /**< number of bytes the task was to read/write. */ + Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */ + void *userdata; /**< pointer provided by the app when starting the task */ +} SDL_AsyncIOOutcome; + +/** + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; + +/** + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + */ +extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode); + +/** + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); + +/** + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure. + * \param ptr a pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); + +/** + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or NULL if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); + +/** + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome); + +/** + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * NULL. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS); + +/** + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + */ +extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue); + +/** + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_asyncio_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h index f159bcd..03e3fb1 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_atomic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -88,15 +88,16 @@ typedef int SDL_SpinLock; * doing. Please be careful using any sort of spinlock!*** * * \param lock a pointer to a lock variable. - * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already - * held. + * \returns true if the lock succeeded, false if the lock is already held. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_UnlockSpinlock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); /** * Lock a spin lock by setting it to a non-zero value. @@ -106,7 +107,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockSpinlock * \sa SDL_UnlockSpinlock @@ -123,7 +126,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock); * * \param lock a pointer to a lock variable. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSpinlock * \sa SDL_TryLockSpinlock @@ -147,9 +152,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -166,7 +172,50 @@ extern __inline void SDL_CompilerBarrier(void); #endif /** - * Insert a memory release barrier. + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); + +/** + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Insert a memory release barrier (macro version). * * Memory barriers are designed to prevent reads and writes from being * reordered by the compiler and being seen out of order on multi-core CPUs. @@ -186,31 +235,47 @@ extern __inline void SDL_CompilerBarrier(void); * For more information on these semantics, take a look at the blog post: * http://preshing.com/20120913/acquire-and-release-semantics * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierReleaseFunction to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() /** - * Insert a memory acquire barrier. + * Insert a memory acquire barrier (macro version). * - * Please refer to SDL_MemoryBarrierReleaseFunction for the details! + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. * - * \threadsafety Obviously this function is safe to use from any thread at any + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_MemoryBarrierReleaseFunction + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -/* !!! FIXME: this should have documentation! */ -#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) +#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") #elif defined(__GNUC__) && defined(__aarch64__) @@ -225,8 +290,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); hard-coded at address 0xffff0fa0 */ typedef void (*SDL_KernelMemoryBarrierFunc)(); -#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() -#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() +#define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() #else #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") @@ -276,9 +341,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * * \threadsafety This macro is safe to use from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay + #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */ #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__) @@ -303,9 +369,10 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * A type representing an atomic integer value. * * This can be used to manage a value that is synchronized across multiple - * CPUs without a race condition; when an app sets a value with SDL_AtomicSet - * all other threads, regardless of the CPU it is running on, will see that - * value when retrieved with SDL_AtomicGet, regardless of CPU caches, etc. + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. * * This is also useful for atomic compare-and-swap operations: a thread can * change the value as long as its current value matches expectations. When @@ -316,14 +383,14 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * this!). * * This is a struct so people don't accidentally use numeric operations on it - * directly. You have to use SDL_Atomic* functions. + * directly. You have to use SDL atomic functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGet - * \sa SDL_AtomicSet - * \sa SDL_AtomicAdd + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt */ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; @@ -336,15 +403,16 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; * \param a a pointer to an SDL_AtomicInt variable to be modified. * \param oldval the old value. * \param newval the new value. - * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. + * \returns true if the atomic variable was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, int oldval, int newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicInt(SDL_AtomicInt *a, int oldval, int newval); /** * Set an atomic variable to a value. @@ -360,11 +428,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicGet + * \sa SDL_GetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_SetAtomicInt(SDL_AtomicInt *a, int v); /** * Get the value of an atomic variable. @@ -377,11 +445,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicSet + * \sa SDL_SetAtomicInt */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); +extern SDL_DECLSPEC int SDLCALL SDL_GetAtomicInt(SDL_AtomicInt *a); /** * Add to an atomic variable. @@ -397,12 +465,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef * \sa SDL_AtomicIncRef */ -extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); +extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v); #ifndef SDL_AtomicIncRef @@ -414,11 +482,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to an SDL_AtomicInt to increment. * \returns the previous value of the atomic variable. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicDecRef */ -#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) +#define SDL_AtomicIncRef(a) SDL_AddAtomicInt(a, 1) #endif #ifndef SDL_AtomicDecRef @@ -429,16 +499,103 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * ***Note: If you don't know what this macro is for, you shouldn't use it!*** * * \param a a pointer to an SDL_AtomicInt to increment. - * \returns SDL_TRUE if the variable reached zero after decrementing, - * SDL_FALSE otherwise. + * \returns true if the variable reached zero after decrementing, false + * otherwise. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. * * \sa SDL_AtomicIncRef */ -#define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) +#define SDL_AtomicDecRef(a) (SDL_AddAtomicInt(a, -1) == 1) #endif +/** + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +typedef struct SDL_AtomicU32 { Uint32 value; } SDL_AtomicU32; + +/** + * Set an atomic variable to a new value if it is currently an old value. + * + * ***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 oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicU32(SDL_AtomicU32 *a, Uint32 oldval, Uint32 newval); + +/** + * Set an atomic variable to a value. + * + * 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. + * \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.2.0. + * + * \sa SDL_GetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v); + +/** + * Get the value of an atomic variable. + * + * ***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. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a); + /** * Set a pointer to a new value if it is currently an old value. * @@ -448,17 +605,17 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v); * \param a a pointer to a pointer. * \param oldval the old pointer value. * \param newval the new pointer value. - * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. + * \returns true if the pointer was set, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwap - * \sa SDL_AtomicGetPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, void *oldval, void *newval); +extern SDL_DECLSPEC bool SDLCALL SDL_CompareAndSwapAtomicPointer(void **a, void *oldval, void *newval); /** * Set a pointer to a value atomically. @@ -472,12 +629,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicGetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); +extern SDL_DECLSPEC void * SDLCALL SDL_SetAtomicPointer(void **a, void *v); /** * Get the value of a pointer atomically. @@ -490,12 +647,12 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AtomicSetPointer(void **a, void *v); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_AtomicCompareAndSwapPointer - * \sa SDL_AtomicSetPointer + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer */ -extern SDL_DECLSPEC void * SDLCALL SDL_AtomicGetPointer(void **a); +extern SDL_DECLSPEC void * SDLCALL SDL_GetAtomicPointer(void **a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h index b7a4b7b..9569382 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_audio.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -33,8 +33,9 @@ * even if the data format changes on either side halfway through. * * An app opens an audio device and binds any number of audio streams to it, - * feeding more data to it as available. When the devices needs more data, it - * will pull it from all bound streams and mix them together for playback. + * feeding more data to the streams as available. When the device needs more + * data, it will pull it from all bound streams and mix them together for + * playback. * * Audio streams can also use an app-provided callback to supply data * on-demand, which maps pretty closely to the SDL2 audio model. @@ -43,6 +44,45 @@ * if you aren't reading from a file) as a basic means to load sound data into * your program. * + * ## Logical audio devices + * + * In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a + * logical device ID that you can bind audio streams to. In almost all cases, + * logical devices can be used anywhere in the API that a physical device is + * normally used. However, since each device opening generates a new logical + * device, different parts of the program (say, a VoIP library, or + * text-to-speech framework, or maybe some other sort of mixer on top of SDL) + * can have their own device opens that do not interfere with each other; each + * logical device will mix its separate audio down to a single buffer, fed to + * the physical device, behind the scenes. As many logical devices as you like + * can come and go; SDL will only have to open the physical device at the OS + * level once, and will manage all the logical devices on top of it + * internally. + * + * One other benefit of logical devices: if you don't open a specific physical + * device, instead opting for the default, SDL can automatically migrate those + * logical devices to different hardware as circumstances change: a user + * plugged in headphones? The system default changed? SDL can transparently + * migrate the logical devices to the correct physical device seamlessly and + * keep playing; the app doesn't even have to know it happened if it doesn't + * want to. + * + * ## Simplified audio + * + * As a simplified model for when a single source of audio is all that's + * needed, an app can use SDL_OpenAudioDeviceStream, which is a single + * function to open an audio device, create an audio stream, bind that stream + * to the newly-opened device, and (optionally) provide a callback for + * obtaining audio data. When using this function, the primary interface is + * the SDL_AudioStream and the device handle is mostly hidden away; destroying + * a stream created through this function will also close the device, stream + * bindings cannot be changed, etc. One other quirk of this is that the device + * is started in a _paused_ state and must be explicitly resumed; this is + * partially to offer a clean migration for SDL2 apps and partially because + * the app might have to do more setup before playback begins; in the + * non-simplified form, nothing will play until a stream is bound to a device, + * so they start _unpaused_. + * * ## Channel layouts * * Audio data passing through SDL is uncompressed PCM data, interleaved. One @@ -73,7 +113,7 @@ * - 4 channels (quad) layout: FL, FR, BL, BR * - 5 channels (4.1) layout: FL, FR, LFE, BL, BR * - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be - * BL, BR) + * SL, SR) * - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR * - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR * @@ -94,7 +134,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -102,19 +141,73 @@ extern "C" { #endif -/* masks for different parts of SDL_AudioFormat. */ +/** + * Mask of bits in an SDL_AudioFormat that contains the format bit size. + * + * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BITSIZE (0xFFu) + +/** + * Mask of bits in an SDL_AudioFormat that contain the floating point flag. + * + * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_FLOAT (1u<<8) + +/** + * Mask of bits in an SDL_AudioFormat that contain the bigendian flag. + * + * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN + * instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12) + +/** + * Mask of bits in an SDL_AudioFormat that contain the signed data flag. + * + * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_AUDIO_MASK_SIGNED (1u<<15) -#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \ - (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) +/** + * Define an SDL_AudioFormat value. + * + * SDL does not support custom audio formats, so this macro is not of much use + * externally, but it can be illustrative as to what the various bits of an + * SDL_AudioFormat mean. + * + * For example, SDL_AUDIO_S32LE looks like this: + * + * ```c + * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32) + * ``` + * + * \param signed 1 for signed data, 0 for unsigned data. + * \param bigendian 1 for bigendian data, 0 for littleendian data. + * \param flt 1 for floating point data, 0 for integer data. + * \param size number of bits per sample. + * \returns a format value in the style of SDL_AudioFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \ + (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) /** * Audio format. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_AUDIO_BITSIZE * \sa SDL_AUDIO_BYTESIZE @@ -144,17 +237,18 @@ typedef enum SDL_AudioFormat /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */ SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */ /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */ -} SDL_AudioFormat; -#if SDL_BYTEORDER == SDL_LIL_ENDIAN -#define SDL_AUDIO_S16 SDL_AUDIO_S16LE -#define SDL_AUDIO_S32 SDL_AUDIO_S32LE -#define SDL_AUDIO_F32 SDL_AUDIO_F32LE -#else -#define SDL_AUDIO_S16 SDL_AUDIO_S16BE -#define SDL_AUDIO_S32 SDL_AUDIO_S32BE -#define SDL_AUDIO_F32 SDL_AUDIO_F32BE -#endif + /* These represent the current system's byteorder. */ + #if SDL_BYTEORDER == SDL_LIL_ENDIAN + SDL_AUDIO_S16 = SDL_AUDIO_S16LE, + SDL_AUDIO_S32 = SDL_AUDIO_S32LE, + SDL_AUDIO_F32 = SDL_AUDIO_F32LE + #else + SDL_AUDIO_S16 = SDL_AUDIO_S16BE, + SDL_AUDIO_S32 = SDL_AUDIO_S32BE, + SDL_AUDIO_F32 = SDL_AUDIO_F32BE + #endif +} SDL_AudioFormat; /** @@ -167,7 +261,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE) @@ -181,7 +275,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8) @@ -195,7 +289,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT) @@ -209,7 +303,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN) @@ -223,7 +317,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x)) @@ -237,7 +331,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED) @@ -251,7 +345,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x)) @@ -265,7 +359,7 @@ typedef enum SDL_AudioFormat * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x)) @@ -275,7 +369,7 @@ typedef enum SDL_AudioFormat * * Zero is used to signify an invalid/null device. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_AudioDeviceID; @@ -286,7 +380,7 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu) @@ -297,14 +391,14 @@ typedef Uint32 SDL_AudioDeviceID; * to signify the app just wants the system to choose a default device instead * of the app providing a specific one. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu) /** * Format specifier for audio data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AudioFormat */ @@ -326,7 +420,7 @@ typedef struct SDL_AudioSpec * * \threadsafety It is safe to call this macro from any thread. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) @@ -350,7 +444,7 @@ typedef struct SDL_AudioSpec * more of them, bind them to an opened audio device, and feed data to them * (or for recording, consume data from them). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -359,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream; /* Function prototypes */ -/** - * \name Driver discovery functions - * - * These functions return the list of built in audio drivers, in the - * order that they are normally initialized by default. - */ -/* @{ */ - /** * Use this function to get the number of built-in audio drivers. * @@ -384,7 +470,7 @@ typedef struct SDL_AudioStream SDL_AudioStream; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDriver */ @@ -408,12 +494,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. @@ -427,7 +512,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); @@ -453,7 +538,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioRecordingDevices @@ -482,7 +567,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice * \sa SDL_GetAudioPlaybackDevices @@ -498,11 +583,10 @@ extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioPlaybackDevices * \sa SDL_GetAudioRecordingDevices - * \sa SDL_GetDefaultAudioInfo */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid); @@ -532,14 +616,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceI * \param spec on return, will be filled with device details. * \param sample_frames pointer to store device buffer size, in sample frames. * Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames); /** * Get the current channel map of an audio device. @@ -558,7 +642,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -633,13 +717,52 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseAudioDevice * \sa SDL_GetAudioDeviceFormat */ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec); +/** + * Determine if an audio device is physical (instead of logical). + * + * An SDL_AudioDeviceID that represents physical hardware is a physical + * device; there is one for each piece of hardware that SDL can see. Logical + * devices are created by calling SDL_OpenAudioDevice or + * SDL_OpenAudioDeviceStream, and while each is associated with a physical + * device, there can be any number of logical devices on one physical device. + * + * For the most part, logical and physical IDs are interchangeable--if you try + * to open a logical device, SDL understands to assign that effort to the + * underlying physical device, etc. However, it might be useful to know if an + * arbitrary device ID is physical or logical. This function reports which. + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a physical device, false if it is logical. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid); + +/** + * Determine if an audio device is a playback device (instead of recording). + * + * This function may return either true or false for invalid device IDs. + * + * \param devid the device ID to query. + * \returns true if devid is a playback device, false if it is recording. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid); + /** * Use this function to pause audio playback on a specified device. * @@ -659,17 +782,17 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDevic * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioDevice * \sa SDL_AudioDevicePaused */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to unpause audio playback on a specified device. @@ -687,17 +810,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev) * created through SDL_OpenAudioDevice() can be. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AudioDevicePaused * \sa SDL_PauseAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev); /** * Use this function to query if an audio device is paused. @@ -710,16 +833,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev * IDs will report themselves as unpaused here. * * \param dev a device opened by SDL_OpenAudioDevice(). - * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise. + * \returns true if device is valid and paused, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioDevice * \sa SDL_ResumeAudioDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); +extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev); /** * Get the gain of an audio device. @@ -738,7 +861,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioDeviceGain */ @@ -753,8 +876,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * Audio devices default to a gain of 1.0f (no change in output). * * Physical devices may not have their gain changed, only logical devices, and - * this function will always return -1 when used on physical devices. While it - * might seem attractive to adjust several logical devices at once in this + * this function will always return false when used on physical devices. While + * it might seem attractive to adjust several logical devices at once in this * way, it would allow an app or library to interfere with another portion of * the program's otherwise-isolated devices. * @@ -767,17 +890,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid * * \param devid the audio device on which to change gain. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioDeviceGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain); /** * Close a previously-opened audio device. @@ -794,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID de * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenAudioDevice */ @@ -819,23 +942,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid); * Binding a stream to a device will set its output format for playback * devices, and its input format for recording devices, so they match the * device's settings. The caller is welcome to change the other end of the - * stream's format at any time. + * stream's format at any time with SDL_SetAudioStreamFormat(). * * \param devid an audio device to bind a stream to. * \param streams an array of audio streams to bind. * \param num_streams number streams listed in the `streams` array. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams); /** * Bind a single audio stream to an audio device. @@ -845,18 +968,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devi * * \param devid an audio device to bind a stream to. * \param stream an audio stream to bind to a device. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams * \sa SDL_UnbindAudioStream * \sa SDL_GetAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream); /** * Unbind a list of audio streams from their audio devices. @@ -867,16 +990,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid * * Unbinding a stream that isn't bound to a device is a legal no-op. * - * \param streams an array of audio streams to unbind. + * \param streams an array of audio streams to unbind. Can be NULL or contain + * NULL. * \param num_streams number streams listed in the `streams` array. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStreams */ -extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams); +extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams); /** * Unbind a single audio stream from its audio device. @@ -884,11 +1008,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **stream * This is a convenience function, equivalent to calling * `SDL_UnbindAudioStreams(&stream, 1)`. * - * \param stream an audio stream to unbind from a device. + * \param stream an audio stream to unbind from a device. Can be NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream */ @@ -907,7 +1031,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindAudioStream * \sa SDL_BindAudioStreams @@ -924,7 +1048,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_GetAudioStreamData @@ -943,7 +1067,9 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream); @@ -953,17 +1079,17 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au * \param stream the SDL_AudioStream to query. * \param src_spec where to store the input audio format; ignored if NULL. * \param dst_spec where to store the output audio format; ignored if NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec); /** * Change the input and output formats of an audio stream. @@ -978,23 +1104,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *s * next sound file, and start putting that new data while the previous sound * file is still queued, and everything will still play back correctly. * + * If a stream is bound to a device, then the format of the side of the stream + * bound to a device cannot be changed (src_spec for recording devices, + * dst_spec for playback devices). Attempts to make a change to this side will + * be ignored, but this will not report an error. The other side's format can + * be changed. + * * \param stream the stream the format is being changed. * \param src_spec the new format of the audio input; if NULL, it is not * changed. * \param dst_spec the new format of the audio output; if NULL, it is not * changed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFormat * \sa SDL_SetAudioStreamFrequencyRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec); /** * Get the frequency ratio of an audio stream. @@ -1006,7 +1138,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *s * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamFrequencyRatio */ @@ -1027,18 +1159,18 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre * \param stream the stream the frequency ratio is being changed. * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01 * and 100. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamFrequencyRatio * \sa SDL_SetAudioStreamFormat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio); /** * Get the gain of an audio stream. @@ -1055,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioS * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGain */ @@ -1074,17 +1206,17 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream * * \param stream the stream on which the gain is being changed. * \param gain the gain. 1.0f is no change, 0.0f is silence. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamGain */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain); /** * Get the current input channel map of an audio stream. @@ -1104,7 +1236,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *str * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1128,7 +1260,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStr * \threadsafety It is safe to call this function from any thread, as it holds * a stream-specific mutex while running. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ @@ -1148,8 +1280,12 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * Data that was previously queued in the stream will still be operated on in * the order that was current when it was added, which is to say you can put @@ -1164,26 +1300,31 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the input channel map on a + * stream bound to a recording device is permitted to change at any time; any + * data added to the stream from the device after this call will have the new + * mapping, but previously-added data will still have the prior mapping. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Set the current output channel map of an audio stream. @@ -1194,12 +1335,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * The output channel map reorders data that leaving a stream via * SDL_GetAudioStreamData. * - * Each item in the array represents an output channel, and its value is the + * Each item in the array represents an input channel, and its value is the * channel that it should be remapped to. To reverse a stereo signal's left * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the - * right channel to both channels of a stereo signal. You cannot change the - * number of channels through a channel map, just reorder them. + * right channel to both channels of a stereo signal. An element in the + * channel map set to -1 instead of a valid channel will mute that channel, + * setting it to a silence value. + * + * You cannot change the number of channels through a channel map, just + * reorder/mute them. * * The output channel map can be changed at any time, as output remapping is * applied during SDL_GetAudioStreamData. @@ -1211,26 +1356,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_Audio * after this call. * * If `count` is not equal to the current number of channels in the audio - * stream's format, this will fail. This is a safety measure to make sure a a - * race condition hasn't changed the format while you this call is setting the + * stream's format, this will fail. This is a safety measure to make sure a + * race condition hasn't changed the format while this call is setting the * channel map. * + * Unlike attempting to change the stream's format, the output channel map on + * a stream bound to a recording device is permitted to change at any time; + * any data added to the stream after this call will have the new mapping, but + * previously-added data will still have the prior mapping. When the channel + * map doesn't match the hardware's channel layout, SDL will convert the data + * before feeding it to the device for playback. + * * \param stream the SDL_AudioStream to change. * \param chmap the new channel map, NULL to reset to default. * \param count The number of channels in the map. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \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! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamInputChannelMap */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count); /** * Add data to the stream. @@ -1246,21 +1398,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_Audi * \param stream the stream the audio data is being added to. * \param buf a pointer to the audio data to add. * \param len the number of bytes to write to the stream. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but if the * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_FlushAudioStream * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); +extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len); /** * Get converted/resampled data from the stream. @@ -1284,7 +1436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *str * stream has a callback set, the caller might need to manage * extra locking. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearAudioStream * \sa SDL_GetAudioStreamAvailable @@ -1311,7 +1463,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamData * \sa SDL_PutAudioStreamData @@ -1322,6 +1474,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str /** * Get the number of bytes currently queued. * + * This is the number of bytes put into a stream as input, not the number that + * can be retrieved as output. Because of several details, it's not possible + * to calculate one number directly from the other. If you need to know how + * much usable data can be retrieved right now, you should use + * SDL_GetAudioStreamAvailable() and not this function. + * * Note that audio streams can change their input format at any time, even if * there is still data queued in a different format, so the returned byte * count will not necessarily match the number of _sample frames_ available. @@ -1344,7 +1502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData * \sa SDL_ClearAudioStream @@ -1361,16 +1519,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream * input, so the complete output becomes available. * * \param stream the audio stream to flush. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** * Clear any pending data in the stream. @@ -1379,19 +1537,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *strea * stream until more is added. * * \param stream the audio stream to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamAvailable * \sa SDL_GetAudioStreamData * \sa SDL_GetAudioStreamQueued * \sa SDL_PutAudioStreamData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream); /** * Use this function to pause audio playback on the audio device associated @@ -1406,16 +1564,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *strea * loading, etc. * * \param stream the audio stream associated with the audio device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream); /** * Use this function to unpause audio playback on the audio device associated @@ -1426,16 +1584,36 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream * to progress again, and audio can be generated. * * \param stream the audio stream associated with the audio device to resume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseAudioStreamDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream); + +/** + * Use this function to query if an audio device associated with a stream is + * paused. + * + * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app + * has to bind a stream before any audio will flow. + * + * \param stream the audio stream associated with the audio device to query. + * \returns true if device is valid and paused, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseAudioStreamDevice + * \sa SDL_ResumeAudioStreamDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream); + /** * Lock an audio stream for serialized access. @@ -1454,16 +1632,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream * all the same attributes (recursive locks are allowed, etc). * * \param stream the audio stream to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream); /** @@ -1472,17 +1650,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream * This unlocks an audio stream after a call to SDL_LockAudioStream. * * \param stream the audio stream to unlock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety You should only call this from the same thread that * previously called SDL_LockAudioStream. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockAudioStream */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); +extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream); /** * A callback that fires when data passes through an SDL_AudioStream. @@ -1519,7 +1697,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stre * is called, so your callback does not need to manage the lock * explicitly. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback * \sa SDL_SetAudioStreamPutCallback @@ -1561,16 +1739,16 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream * from the stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamPutCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** * Set a callback that runs when data is added to an audio stream. @@ -1610,16 +1788,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStre * stream. * \param userdata an opaque pointer provided to the callback for its own * personal use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. This only fails if `stream` is NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. This only fails if `stream` is NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAudioStreamGetCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata); /** @@ -1637,7 +1815,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStre * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateAudioStream */ @@ -1699,7 +1877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAudioStreamDevice * \sa SDL_ResumeAudioStreamDevice @@ -1737,7 +1915,7 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_Audi * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetAudioPostmixCallback */ @@ -1788,14 +1966,14 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio * \param devid the ID of an opened audio device. * \param callback a callback function to be called. Can be NULL. * \param userdata app-controlled pointer passed to callback. Can be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata); /** @@ -1839,7 +2017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * Example: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len); + * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len); * ``` * * Note that the SDL_LoadWAV function does this same thing for you, but in a @@ -1850,19 +2028,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * ``` * * \param src the data source for the WAVE data. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE * data's format details on successful return. * \param audio_buf a pointer filled with the audio data, allocated by the * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1871,12 +2049,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDevice * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Loads a WAV from a file path. @@ -1884,7 +2062,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * This is a convenience function that is effectively the same as: * * ```c - * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), SDL_TRUE, spec, audio_buf, audio_len); + * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len); * ``` * * \param path the file path of the WAV file to open. @@ -1894,11 +2072,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * function. * \param audio_len a pointer filled with the length of the audio data buffer * in bytes. - * \returns SDL_TRUE on success. `audio_buf` will be filled with a pointer to - * an allocated buffer containing the audio data, and `audio_len` is + * \returns true on success. `audio_buf` will be filled with a pointer to an + * allocated buffer containing the audio data, and `audio_len` is * filled with the length of that audio buffer in bytes. * - * This function returns SDL_FALSE if the .WAV file cannot be opened, + * This function returns false if the .WAV file cannot be opened, * uses an unknown data format, or is corrupt; call SDL_GetError() * for more information. * @@ -1907,12 +2085,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_free * \sa SDL_LoadWAV_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); +extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); /** * Mix audio data in a specified format. @@ -1941,14 +2119,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * \param len the length of the audio buffer in bytes. * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full * audio volume. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); +extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume); /** * Convert some audio data of one format to another format. @@ -1971,14 +2149,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, * which should be freed with SDL_free(). On error, it will be * NULL. * \param dst_len will be filled with the len of dst_data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len); /** * Get the human readable name of an audio format. @@ -1989,7 +2167,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format); @@ -2005,7 +2183,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h index f418c61..a6b47cf 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_begin_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,15 @@ /* WIKI CATEGORY: BeginCode */ /** - * SDL_begin_code.h sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * # CategoryBeginCode + * + * `SDL_begin_code.h` sets things up for C dynamic library function + * definitions, static inlined functions, and structures aligned at 4-byte + * alignment. If you don't like ugly C preprocessor code, don't look at this + * file. :) + * + * SDL's headers use this; applications generally should not include this + * header directly. */ /* This shouldn't be nested -- included it around code only. */ @@ -33,6 +39,259 @@ #endif #define SDL_begin_code_h +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a symbol as deprecated. + * + * A function is marked deprecated by adding this macro to its declaration: + * + * ```c + * extern SDL_DEPRECATED int ThisFunctionWasABadIdea(void); + * ``` + * + * Compilers with deprecation support can give a warning when a deprecated + * function is used. This symbol may be used in SDL's headers, but apps are + * welcome to use it for their own interfaces as well. + * + * SDL, on occasion, might deprecate a function for various reasons. However, + * SDL never removes symbols before major versions, so deprecated interfaces + * in SDL3 will remain available until SDL4, where it would be expected an app + * would have to take steps to migrate anyhow. + * + * On compilers without a deprecation mechanism, this is defined to nothing, + * and using a deprecated function will not generate a warning. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DEPRECATED __attribute__((deprecated)) + +/** + * A macro to tag a symbol as a public API. + * + * SDL uses this macro for all its public functions. On some targets, it is + * used to signal to the compiler that this function needs to be exported from + * a shared library, but it might have other side effects. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_DECLSPEC __attribute__ ((visibility("default"))) + +/** + * A macro to set a function's calling conventions. + * + * SDL uses this macro for all its public functions, and any callbacks it + * defines. This macro guarantees that calling conventions match between SDL + * and the app, even if the two were built with different compilers or + * optimization settings. + * + * When writing a callback function, it is very important for it to be + * correctly tagged with SDLCALL, as mismatched calling conventions can cause + * strange behaviors and can be difficult to diagnose. Plus, on many + * platforms, SDLCALL is defined to nothing, so compilers won't be able to + * warn that the tag is missing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDLCALL __cdecl + +/** + * A macro to request a function be inlined. + * + * This is a hint to the compiler to inline a function. The compiler is free + * to ignore this request. On compilers without inline support, this is + * defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INLINE __inline + +/** + * A macro to demand a function be inlined. + * + * This is a command to the compiler to inline a function. SDL uses this macro + * in its public headers for a handful of simple functions. On compilers + * without forceinline support, this is defined to `static SDL_INLINE`, which + * is often good enough. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FORCE_INLINE __forceinline + +/** + * A macro to tag a function as never-returning. + * + * This is a hint to the compiler that a function does not return. An example + * of a function like this is the C runtime's exit() function. + * + * This hint can lead to code optimizations, and help analyzers understand + * code flow better. On compilers without noreturn support, this is defined to + * nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NORETURN __attribute__((noreturn)) + +/** + * A macro to tag a function as never-returning (for analysis purposes). + * + * This is almost identical to SDL_NORETURN, except functions marked with this + * _can_ actually return. The difference is that this isn't used for code + * generation, but rather static analyzers use this information to assume + * truths about program state and available code paths. Specifically, this tag + * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this + * tag behind the scenes. Generally, apps that don't understand the specific + * use-case for this tag should avoid using it directly. + * + * On compilers without analyzer_noreturn support, this is defined to nothing. + * + * This symbol is used in SDL's headers, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) + + +/** + * A macro to signal that a case statement without a `break` is intentional. + * + * C compilers have gotten more aggressive about warning when a switch's + * `case` block does not end with a `break` or other flow control statement, + * flowing into the next case's code, as this is a common accident that leads + * to strange bugs. But sometimes falling through to the next case is the + * correct and desired behavior. This symbol lets an app communicate this + * intention to the compiler, so it doesn't generate a warning. + * + * It is used like this: + * + * ```c + * switch (x) { + * case 1: + * DoSomethingOnlyForOne(); + * SDL_FALLTHROUGH; // tell the compiler this was intentional. + * case 2: + * DoSomethingForOneAndTwo(); + * break; + * } + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_FALLTHROUGH [[fallthrough]] + +/** + * A macro to tag a function's return value as critical. + * + * This is a hint to the compiler that a function's return value should not be + * ignored. + * + * If an NODISCARD function's return value is thrown away (the function is + * called as if it returns `void`), the compiler will issue a warning. + * + * While it's generally good practice to check return values for errors, often + * times legitimate programs do not for good reasons. Be careful about what + * functions are tagged as NODISCARD. It operates best when used on a function + * that's failure is surprising and catastrophic; a good example would be a + * program that checks the return values of all its file write function calls + * but not the call to close the file, which it assumes incorrectly never + * fails. + * + * Function callers that want to throw away a NODISCARD return value can call + * the function with a `(void)` cast, which informs the compiler the act is + * intentional. + * + * On compilers without nodiscard support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NODISCARD [[nodiscard]] + +/** + * A macro to tag a function as an allocator. + * + * This is a hint to the compiler that a function is an allocator, like + * malloc(), with certain rules. A description of how GCC treats this hint is + * here: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute + * + * On compilers without allocator tag support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MALLOC __declspec(allocator) __desclspec(restrict) + +/** + * A macro to tag a function as returning a certain allocation. + * + * This is a hint to the compiler that a function allocates and returns a + * specific amount of memory based on one of its arguments. For example, the C + * runtime's malloc() function could use this macro with an argument of 1 + * (first argument to malloc is the size of the allocation). + * + * On compilers without alloc_size support, this is defined to nothing. + * + * Most apps don't need to, and should not, use this directly. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALLOC_SIZE(p) __attribute__((alloc_size(p))) + +/** + * A macro to tag a pointer variable, to help with pointer aliasing. + * + * A good explanation of the restrict keyword is here: + * + * https://en.wikipedia.org/wiki/Restrict + * + * On compilers without restrict support, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_RESTRICT __restrict__ + +/** + * Check if the compiler supports a given builtin functionality. + * + * This allows preprocessor checks for things that otherwise might fail to + * compile. + * + * Supported by virtually all clang versions and more-recent GCCs. Use this + * instead of checking the clang version if possible. + * + * On compilers without has_builtin support, this is defined to 0 (always + * false). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_HAS_BUILTIN(x) __has_builtin(x) + +/* end of wiki documentation section. */ +#endif + +#ifndef SDL_HAS_BUILTIN +#ifdef __has_builtin +#define SDL_HAS_BUILTIN(x) __has_builtin(x) +#else +#define SDL_HAS_BUILTIN(x) 0 +#endif +#endif + #ifndef SDL_DEPRECATED # if defined(__GNUC__) && (__GNUC__ >= 4) /* technically, this arrived in gcc 3.1, but oh well. */ # define SDL_DEPRECATED __attribute__((deprecated)) @@ -53,7 +312,7 @@ /* Some compilers use a special export keyword */ #ifndef SDL_DECLSPEC -# if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_CYGWIN) || defined(SDL_PLATFORM_GDK) +# if defined(SDL_PLATFORM_WINDOWS) # ifdef DLL_EXPORT # define SDL_DECLSPEC __declspec(dllexport) # else @@ -70,7 +329,7 @@ /* By default SDL uses the C calling convention */ #ifndef SDLCALL -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINRT) || defined(SDL_PLATFORM_GDK)) && !defined(__GNUC__) +#if defined(SDL_PLATFORM_WINDOWS) && !defined(__GNUC__) #define SDLCALL __cdecl #else #define SDLCALL diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h index 72be082..7435ce6 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_bits.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -36,10 +36,6 @@ extern "C" { #endif -/** - * \file SDL_bits.h - */ - #if defined(__WATCOMC__) && defined(__386__) extern __inline int _SDL_bsr_watcom(Uint32); #pragma aux _SDL_bsr_watcom = \ @@ -65,7 +61,7 @@ extern __inline int _SDL_bsr_watcom(Uint32); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) { @@ -82,10 +78,10 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) return -1; } return _SDL_bsr_watcom(x); -#elif defined(_MSC_VER) +#elif defined(_MSC_VER) && _MSC_VER >= 1400 unsigned long index; if (_BitScanReverse(&index, x)) { - return index; + return (int)index; } return -1; #else @@ -120,8 +116,7 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * Determine if a unsigned 32-bit value has exactly one bit set. * * If there are no bits set (`x` is zero), or more than one bit set, this - * returns SDL_FALSE. If any one bit is exclusively set, this returns - * SDL_TRUE. + * returns false. If any one bit is exclusively set, this returns true. * * Note that this is a forced-inline function in a header, and not a public * API function available in the SDL library (which is to say, the code is @@ -129,18 +124,18 @@ SDL_FORCE_INLINE int SDL_MostSignificantBitIndex32(Uint32 x) * be able to find this function inside SDL itself). * * \param x the 32-bit value to examine. - * \returns SDL_TRUE if exactly one bit is set in `x`, SDL_FALSE otherwise. + * \returns true if exactly one bit is set in `x`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_HasExactlyOneBitSet32(Uint32 x) +SDL_FORCE_INLINE bool SDL_HasExactlyOneBitSet32(Uint32 x) { if (x && !(x & (x - 1))) { - return SDL_TRUE; + return true; } - return SDL_FALSE; + return false; } /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h index 76aa197..8f00cbc 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_blendmode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,7 @@ * * Blend modes decide how two colors will mix together. There are both * standard modes for basic needs and a means to create custom modes, - * dictating what sort of math to do what on what color components. + * dictating what sort of math to do on what color components. */ #ifndef SDL_blendmode_h_ @@ -45,7 +45,7 @@ extern "C" { * * Additional values may be obtained from SDL_ComposeCustomBlendMode. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_ComposeCustomBlendMode */ @@ -64,7 +64,7 @@ typedef Uint32 SDL_BlendMode; * The blend operation used when combining source and destination pixel * components. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendOperation { @@ -83,7 +83,7 @@ typedef enum SDL_BlendOperation * operation. The comma-separated factors listed above are always applied in * the component order red, green, blue, and alpha. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_BlendFactor { @@ -177,7 +177,9 @@ typedef enum SDL_BlendFactor * \returns an SDL_BlendMode that represents the chosen factors and * operations. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode * \sa SDL_GetRenderDrawBlendMode diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h index 3d4c57e..c4d0596 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_camera.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -28,13 +28,51 @@ * devices can be enumerated, queried, and opened. Once opened, it will * provide SDL_Surface objects as new frames of video come in. These surfaces * can be uploaded to an SDL_Texture or processed as pixels in memory. + * + * Several platforms will alert the user if an app tries to access a camera, + * and some will present a UI asking the user if your application should be + * allowed to obtain images at all, which they can deny. A successfully opened + * camera will not provide images until permission is granted. Applications, + * after opening a camera device, can see if they were granted access by + * either polling with the SDL_GetCameraPermissionState() function, or waiting + * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED + * event. Platforms that don't have any user approval process will report + * approval immediately. + * + * Note that SDL cameras only provide video as individual frames; they will + * not provide full-motion video encoded in a movie file format, although an + * app is free to encode the acquired frames into any format it likes. It also + * does not provide audio from the camera hardware through this API; not only + * do many webcams not have microphones at all, many people--from streamers to + * people on Zoom calls--will want to use a separate microphone regardless of + * the camera. In any case, recorded audio will be available through SDL's + * audio API no matter what hardware provides the microphone. + * + * ## Camera gotchas + * + * Consumer-level camera hardware tends to take a little while to warm up, + * once the device has been opened. Generally most camera apps have some sort + * of UI to take a picture (a button to snap a pic while a preview is showing, + * some sort of multi-second countdown for the user to pose, like a photo + * booth), which puts control in the users' hands, or they are intended to + * stay on for long times (Pokemon Go, etc). + * + * It's not uncommon that a newly-opened camera will provide a couple of + * completely black frames, maybe followed by some under-exposed images. If + * taking a single frame automatically, or recording video from a camera's + * input without the user initiating it from a preview, it could be wise to + * drop the first several frames (if not the first several _seconds_ worth of + * frames!) before using images from a camera. */ #ifndef SDL_camera_h_ #define SDL_camera_h_ +#include #include -#include +#include +#include +#include #include /* Set up for C function definitions, even when using C++ */ @@ -50,7 +88,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -59,7 +97,7 @@ typedef Uint32 SDL_CameraID; /** * The opaque structure used to identify an opened SDL camera. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Camera SDL_Camera; @@ -69,7 +107,7 @@ typedef struct SDL_Camera SDL_Camera; * Cameras often support multiple formats; each one will be encapsulated in * this struct. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetCameraSupportedFormats * \sa SDL_GetCameraFormat @@ -87,7 +125,7 @@ typedef struct SDL_CameraSpec /** * The position of camera in relation to system device. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCameraPosition */ @@ -116,7 +154,7 @@ typedef enum SDL_CameraPosition * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameraDriver */ @@ -140,7 +178,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumCameraDrivers */ @@ -158,7 +196,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); @@ -173,7 +211,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -211,7 +249,7 @@ extern SDL_DECLSPEC SDL_CameraID * SDLCALL SDL_GetCameras(int *count); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_OpenCamera @@ -227,7 +265,7 @@ extern SDL_DECLSPEC SDL_CameraSpec ** SDLCALL SDL_GetCameraSupportedFormats(SDL_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -246,7 +284,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras */ @@ -265,7 +303,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * You can call SDL_GetCameraFormat() to get the actual data format if passing * a NULL spec here. You can see the exact specs a device can support without - * conversion with SDL_GetCameraSupportedSpecs(). + * conversion with SDL_GetCameraSupportedFormats(). * * SDL will not attempt to emulate framerate; it will try to set the hardware * to the rate closest to the requested speed, but it won't attempt to limit @@ -278,10 +316,11 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * the camera, and they can choose Yes or No at that point. Until they do, the * camera will not be usable. The app should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. On - * platforms that don't require explicit user approval (and perhaps in places - * where the user previously permitted access), the approval event might come - * immediately, but it might come seconds, minutes, or hours later! + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. On platforms that don't require explicit user approval (and + * perhaps in places where the user previously permitted access), the approval + * event might come immediately, but it might come seconds, minutes, or hours + * later! * * \param instance_id the camera device instance ID. * \param spec the desired format for data the device will provide. Can be @@ -291,7 +330,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCameras * \sa SDL_GetCameraFormat @@ -324,7 +363,7 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera * \sa SDL_CloseCamera @@ -340,7 +379,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ @@ -355,7 +394,7 @@ extern SDL_DECLSPEC SDL_CameraID SDLCALL SDL_GetCameraID(SDL_Camera *camera); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera *camera); @@ -366,23 +405,24 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetCameraProperties(SDL_Camera * be converting to this format behind the scenes. * * If the system is waiting for the user to approve access to the camera, as - * some platforms require, this will return SDL_FALSE, but this isn't - * necessarily a fatal error; you should either wait for an + * some platforms require, this will return false, but this isn't necessarily + * a fatal error; you should either wait for an * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event, - * or poll SDL_IsCameraApproved() occasionally until it returns non-zero. + * or poll SDL_GetCameraPermissionState() occasionally until it returns + * non-zero. * * \param camera opened camera device. * \param spec the SDL_CameraSpec to be initialized by this function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenCamera */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_CameraSpec *spec); /** * Acquire a frame. @@ -404,14 +444,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * After use, the frame should be released with SDL_ReleaseCameraFrame(). If * you don't do this, the system may stop providing more video! * - * Do not call SDL_FreeSurface() on the returned surface! It must be given + * Do not call SDL_DestroySurface() on the returned surface! It must be given * back to the camera subsystem with SDL_ReleaseCameraFrame! * * If the system is waiting for the user to approve access to the camera, as * some platforms require, this will return NULL (no frames available); you * should either wait for an SDL_EVENT_CAMERA_DEVICE_APPROVED (or - * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll SDL_IsCameraApproved() - * occasionally until it returns non-zero. + * SDL_EVENT_CAMERA_DEVICE_DENIED) event, or poll + * SDL_GetCameraPermissionState() occasionally until it returns non-zero. * * \param camera opened camera device. * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on @@ -421,7 +461,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReleaseCameraFrame */ @@ -449,7 +489,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_AcquireCameraFrame(SDL_Camera *cam * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireCameraFrame */ @@ -464,9 +504,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseCameraFrame(SDL_Camera *camera, SDL_ * \threadsafety It is safe to call this function from any thread, but no * thread may reference `device` once this function is called. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_OpenCameraWithSpec * \sa SDL_OpenCamera */ extern SDL_DECLSPEC void SDLCALL SDL_CloseCamera(SDL_Camera *camera); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h index 4d4ae32..0d3cbb4 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_clipboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,51 @@ * from other processes and publishing information of its own. * * This is not just text! SDL apps can access and publish data by mimetype. + * + * ## Basic use (text) + * + * Obtaining and publishing simple text to the system clipboard is as easy as + * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively. + * These deal with C strings in UTF-8 encoding. Data transmission and encoding + * conversion is completely managed by SDL. + * + * ## Clipboard callbacks (data other than text) + * + * Things get more complicated when the clipboard contains something other + * than text. Not only can the system clipboard contain data of any type, in + * some cases it can contain the same data in different formats! For example, + * an image painting app might let the user copy a graphic to the clipboard, + * and offers it in .BMP, .JPG, or .PNG format for other apps to consume. + * + * Obtaining clipboard data ("pasting") like this is a matter of calling + * SDL_GetClipboardData() and telling it the mimetype of the data you want. + * But how does one know if that format is available? SDL_HasClipboardData() + * can report if a specific mimetype is offered, and + * SDL_GetClipboardMimeTypes() can provide the entire list of mimetypes + * available, so the app can decide what to do with the data and what formats + * it can support. + * + * Setting the clipboard ("copying") to arbitrary data is done with + * SDL_SetClipboardData. The app does not provide the data in this call, but + * rather the mimetypes it is willing to provide and a callback function. + * During the callback, the app will generate the data. This allows massive + * data sets to be provided to the clipboard, without any data being copied + * before it is explicitly requested. More specifically, it allows an app to + * offer data in multiple formats without providing a copy of all of them + * upfront. If the app has an image that it could provide in PNG or JPG + * format, it doesn't have to encode it to either of those unless and until + * something tries to paste it. + * + * ## Primary Selection + * + * The X11 and Wayland video targets have a concept of the "primary selection" + * in addition to the usual clipboard. This is generally highlighted (but not + * explicitly copied) text from various apps. SDL offers APIs for this through + * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers + * these APIs on platforms without this concept, too, but only so far that it + * will keep a copy of a string that the app sets for later retrieval; the + * operating system will not ever attempt to change the string externally if + * it doesn't support a primary selection. */ #ifndef SDL_clipboard_h_ @@ -46,27 +91,31 @@ extern "C" { * Put UTF-8 text into the clipboard. * * \param text the text to store in the clipboard. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_HasClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text); /** * Get UTF-8 text from the clipboard. * - * This functions returns empty string if there was not enough memory left for - * a copy of the clipboard's content. + * This functions returns an empty string if there was 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 * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardText * \sa SDL_SetClipboardText @@ -76,40 +125,46 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void); /** * Query whether the clipboard exists and contains a non-empty text string. * - * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not. + * \returns true if the clipboard has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetClipboardText * \sa SDL_SetClipboardText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void); /** * Put UTF-8 text into the primary selection. * * \param text the text to store in the primary selection. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_HasPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPrimarySelectionText(const char *text); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text); /** * Get UTF-8 text from the primary selection. * - * This functions returns empty string if there was not enough memory left for - * a copy of the primary selection's content. + * This functions returns an empty string if there was 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 * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasPrimarySelectionText * \sa SDL_SetPrimarySelectionText @@ -120,15 +175,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void); * Query whether the primary selection exists and contains a non-empty text * string. * - * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it - * does not. + * \returns true if the primary selection has text, or false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrimarySelectionText * \sa SDL_SetPrimarySelectionText */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void); /** * Callback function that will be called when data for the specified mime-type @@ -148,7 +204,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void); * breakage in receiving applications. 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.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -160,7 +216,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c * * \param userdata a pointer to provided user data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ @@ -170,13 +226,13 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * Offer clipboard data to the OS. * * Tell the operating system that the application is offering clipboard data - * for each of the proivded mime-types. Once another application requests the - * data the callback function will be called allowing it to generate and + * for each of the provided mime-types. Once another application requests the + * data the callback function will be called, allowing it to generate and * 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 - * document) + * document). * * \param callback a function pointer to the function that provides the * clipboard data. @@ -185,28 +241,32 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); * \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 num_mime_types the number of mime-types in the mime_types list. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearClipboardData * \sa SDL_GetClipboardData * \sa SDL_HasClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); +extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** * Clear the clipboard data. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void); /** * Get the data from clipboard for a given mime type. @@ -220,7 +280,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearClipboardData(void); * for more information. This should be freed with SDL_free() when it * is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasClipboardData * \sa SDL_SetClipboardData @@ -231,15 +293,34 @@ 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 SDL_TRUE if there exists data in clipboard for the provided mime - * type, SDL_FALSE if it does not. + * \returns true if there exists data in clipboard for the provided mime type, + * false if it does not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetClipboardData * \sa SDL_GetClipboardData */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type); + +/** + * Retrieve the list of mime types available in the clipboard. + * + * \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 + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetClipboardData + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetClipboardMimeTypes(size_t *num_mime_types); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h index fa4d3d1..da1dea7 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_close_code.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -21,7 +21,10 @@ /* * This file reverses the effects of SDL_begin_code.h and should be included - * after you finish any function and structure declarations in your headers + * after you finish any function and structure declarations in your headers. + * + * SDL's headers use this; applications generally should not include this + * header directly. */ #ifndef SDL_begin_code_h diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h index dcbdcea..747bd35 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_copying.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h index e7ced26..1745bd9 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_cpuinfo.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,6 +29,12 @@ * These functions are largely concerned with reporting if the system has * access to various SIMD instruction sets, but also has other important info * to share, such as system RAM size and number of logical CPU cores. + * + * CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are + * available on all platforms, even if they don't make sense (an ARM processor + * will never have SSE and an x86 processor will never have NEON, for example, + * but these functions still exist and will simply return false in these + * cases). */ #ifndef SDL_cpuinfo_h_ @@ -49,20 +55,22 @@ extern "C" { * processors have a 128 byte cache line. We use the larger value to be * generally safe. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_CACHELINE_SIZE 128 /** - * Get the number of CPU cores available. + * Get the number of logical CPU cores available. * * \returns the total number of logical CPU cores. On CPUs that include * technologies such as hyperthreading, the number of logical cores * may be more than the number of physical cores. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); +extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); /** * Determine the L1 cache line size of the CPU. @@ -72,7 +80,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCount(void); * * \returns the L1 cache line size of the CPU, in bytes. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); @@ -82,144 +92,164 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * This always returns false on CPUs that aren't using PowerPC instruction * sets. * - * \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not. + * \returns true if the CPU has AltiVec features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); /** * Determine whether the CPU has MMX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not. + * \returns true if the CPU has MMX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); /** * Determine whether the CPU has SSE features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not. + * \returns true if the CPU has SSE features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); /** * Determine whether the CPU has SSE2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); /** * Determine whether the CPU has SSE3 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not. + * \returns true if the CPU has SSE3 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE41 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); /** * Determine whether the CPU has SSE4.1 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.1 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE42 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); /** * Determine whether the CPU has SSE4.2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not. + * \returns true if the CPU has SSE4.2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasSSE * \sa SDL_HasSSE2 * \sa SDL_HasSSE3 * \sa SDL_HasSSE41 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasSSE42(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); /** * Determine whether the CPU has AVX features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX features or SDL_FALSE if not. + * \returns true if the CPU has AVX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX2 * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); /** * Determine whether the CPU has AVX2 features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX2 features or SDL_FALSE if not. + * \returns true if the CPU has AVX2 features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX512F */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); /** * Determine whether the CPU has AVX-512F (foundation) features. * * This always returns false on CPUs that aren't using Intel instruction sets. * - * \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not. + * \returns true if the CPU has AVX-512F features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasAVX * \sa SDL_HasAVX2 */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); /** * Determine whether the CPU has ARM SIMD (ARMv6) features. @@ -228,24 +258,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void); * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not. + * \returns true if the CPU has ARM SIMD features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasNEON */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); /** * Determine whether the CPU has NEON (ARM SIMD) features. * * This always returns false on CPUs that aren't using ARM instruction sets. * - * \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not. + * \returns true if the CPU has ARM NEON features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); /** * Determine whether the CPU has LSX (LOONGARCH SIMD) features. @@ -253,12 +287,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LSX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LSX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); /** * Determine whether the CPU has LASX (LOONGARCH SIMD) features. @@ -266,19 +301,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLSX(void); * This always returns false on CPUs that aren't using LOONGARCH instruction * sets. * - * \returns SDL_TRUE if the CPU has LOONGARCH LASX features or SDL_FALSE if - * not. + * \returns true if the CPU has LOONGARCH LASX features or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasLASX(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); /** * Get the amount of RAM configured in the system. * * \returns the amount of RAM configured in the system in MiB. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); @@ -297,7 +335,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); * \returns the alignment in bytes needed for available, known SIMD * instructions. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc * \sa SDL_aligned_free diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h index 8a198a8..460038f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_dialog.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,12 +23,23 @@ * # CategoryDialog * * File dialog support. + * + * SDL offers file dialogs, to let users select files with native GUI + * interfaces. There are "open" dialogs, "save" dialogs, and folder selection + * dialogs. The app can control some details, such as filtering to specific + * files, or whether multiple files can be selected by the user. + * + * Note that launching a file dialog is a non-blocking operation; control + * returns to the app immediately, and a callback is called later (possibly in + * another thread) when the user makes a choice. */ #ifndef SDL_dialog_h_ #define SDL_dialog_h_ +#include #include +#include #include #include @@ -48,12 +59,13 @@ extern "C" { * hyphens, underscores and periods. Alternatively, the whole string can be a * single asterisk ("*"), which serves as an "All files" filter. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef struct SDL_DialogFileFilter { @@ -75,31 +87,34 @@ typedef struct SDL_DialogFileFilter * is a null-terminated list of pointers to C strings, each containing a * path. * - * The filelist argument does not need to be freed; it will automatically be - * freed when the callback returns. + * The filelist argument should not be freed; it will automatically be freed + * when the callback returns. * * The filter argument is the index of the filter that was selected, or -1 if * no filter was selected or if the platform or method doesn't support * fetching the selected filter. * + * In Android, the `filelist` are `content://` URIs. They should be opened + * using SDL_IOFromFile() with appropriate modes. This applies both to open + * and save file dialog. + * * \param userdata an app-provided pointer, for the callback's use. * \param filelist the file(s) chosen by the user. * \param filter index of the selected filter. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * const *filelist, int filter); /** * Displays a dialog that lets the user select a file on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -117,47 +132,41 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location, bool allow_many); /** * Displays a dialog that lets the user choose a new or existing file on their * filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -174,44 +183,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is the index of the filter selected by the user, - * or one past the index of the last filter (therefore the - * index of the terminating NULL filter) if no filter was - * chosen, or -1 if the platform does not support detecting - * the selected filter. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \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 SDL_DialogFileFilter's. May be NULL. Not all - * platforms support this option, and platforms that do support - * it may allow the user to ignore the filters. + * \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 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. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_DialogFileFilter * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFolderDialog + * \sa SDL_ShowFileDialogWithProperties */ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const SDL_DialogFileFilter *filters, int nfilters, const char *default_location); /** * Displays a dialog that lets the user select a folder on their filesystem. * - * This function should only be invoked from the main thread. - * * This is an asynchronous function; it will return immediately, and the * result will be passed to the callback. * @@ -229,31 +232,105 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowSaveFileDialog(SDL_DialogFileCallback c * requires an event-handling loop. Apps that do not use SDL to handle events * should add a call to SDL_PumpEvents in their main loop. * - * \param callback an SDL_DialogFileCallback to be invoked when the user - * selects a file and accepts, or cancels the dialog, or an - * error occurs. The first argument is a null-terminated list - * of C strings, representing the paths chosen by the user. - * The list will be empty if the user canceled the dialog, and - * it will be NULL if an error occurred. If an error occurred, - * it can be fetched with SDL_GetError(). The second argument - * is the userdata pointer passed to the function. The third - * argument is always -1 for SDL_ShowOpenFolderDialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. * \param userdata an optional pointer to pass extra data to the callback when * it will be invoked. - * \param window the window that the dialog should be modal for. May be NULL. + * \param window the window that the dialog should be modal for, may be NULL. * Not all platforms support this option. - * \param default_location the default folder or file to start the dialog at. - * May be NULL. Not all platforms support this option. + * \param default_location the default folder or file to start the dialog at, + * may be NULL. Not all platforms support this option. * \param allow_many if non-zero, the user will be allowed to select multiple * entries. Not all platforms support this option. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DialogFileCallback * \sa SDL_ShowOpenFileDialog * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowFileDialogWithProperties */ -extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, SDL_bool allow_many); +extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback callback, void *userdata, SDL_Window *window, const char *default_location, bool allow_many); + +/** + * Various types of file dialogs. + * + * This is used by SDL_ShowFileDialogWithProperties() to decide what kind of + * dialog to present to the user. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_ShowFileDialogWithProperties + */ +typedef enum SDL_FileDialogType +{ + SDL_FILEDIALOG_OPENFILE, + SDL_FILEDIALOG_SAVEFILE, + SDL_FILEDIALOG_OPENFOLDER +} SDL_FileDialogType; + +/** + * Create and launch a file dialog with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_FILE_DIALOG_FILTERS_POINTER`: a pointer to a list of + * SDL_DialogFileFilter structs, which will be used as filters for + * file-based selections. Ignored if the dialog is an "Open Folder" dialog. + * If non-NULL, the array of filters must remain valid at least until the + * callback is invoked. + * - `SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER`: the number of filters in the + * array of filters, if it exists. + * - `SDL_PROP_FILE_DIALOG_WINDOW_POINTER`: the window that the dialog should + * be modal for. + * - `SDL_PROP_FILE_DIALOG_LOCATION_STRING`: the default folder or file to + * start the dialog at. + * - `SDL_PROP_FILE_DIALOG_MANY_BOOLEAN`: true to allow the user to select + * more than one entry. + * - `SDL_PROP_FILE_DIALOG_TITLE_STRING`: the title for the dialog. + * - `SDL_PROP_FILE_DIALOG_ACCEPT_STRING`: the label that the accept button + * should have. + * - `SDL_PROP_FILE_DIALOG_CANCEL_STRING`: the label that the cancel button + * should have. + * + * Note that each platform may or may not support any of the properties. + * + * \param type the type of file dialog. + * \param callback a function pointer to be invoked when the user selects a + * file and accepts, or cancels the dialog, or an error + * occurs. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param props the properties to use. + * + * \threadsafety This function should be called only from the main thread. The + * callback may be invoked from the same thread or from a + * different one, depending on the OS's constraints. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_FileDialogType + * \sa SDL_DialogFileCallback + * \sa SDL_DialogFileFilter + * \sa SDL_ShowOpenFileDialog + * \sa SDL_ShowSaveFileDialog + * \sa SDL_ShowOpenFolderDialog + */ +extern SDL_DECLSPEC void SDLCALL SDL_ShowFileDialogWithProperties(SDL_FileDialogType type, SDL_DialogFileCallback callback, void *userdata, SDL_PropertiesID props); + +#define SDL_PROP_FILE_DIALOG_FILTERS_POINTER "SDL.filedialog.filters" +#define SDL_PROP_FILE_DIALOG_NFILTERS_NUMBER "SDL.filedialog.nfilters" +#define SDL_PROP_FILE_DIALOG_WINDOW_POINTER "SDL.filedialog.window" +#define SDL_PROP_FILE_DIALOG_LOCATION_STRING "SDL.filedialog.location" +#define SDL_PROP_FILE_DIALOG_MANY_BOOLEAN "SDL.filedialog.many" +#define SDL_PROP_FILE_DIALOG_TITLE_STRING "SDL.filedialog.title" +#define SDL_PROP_FILE_DIALOG_ACCEPT_STRING "SDL.filedialog.accept" +#define SDL_PROP_FILE_DIALOG_CANCEL_STRING "SDL.filedialog.cancel" /* Ends C function definitions when using C++ */ #ifdef __cplusplus @@ -261,4 +338,4 @@ extern SDL_DECLSPEC void SDLCALL SDL_ShowOpenFolderDialog(SDL_DialogFileCallback #endif #include -#endif /* SDL_joystick_h_ */ +#endif /* SDL_dialog_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h index cc557d6..65d4e96 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_egl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h index cb3d7f3..a34e9d4 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_endian.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,20 @@ /** * # CategoryEndian * - * Functions for reading and writing endian-specific values. + * Functions converting endian-specific values to different byte orders. + * + * These functions either unconditionally swap byte order (SDL_Swap16, + * SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's + * native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE, + * SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the + * latter case, the functionality is provided by macros that become no-ops if + * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE + * does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC + * processor (bigendian), the macros behavior is reversed. + * + * The swap routines are inline functions, and attempt to use compiler + * intrinsics, inline assembly, and other magic to make byteswapping + * efficient. */ #ifndef SDL_endian_h_ @@ -51,12 +64,71 @@ _m_prefetch(void *__P) * \name The two types of endianness */ /* @{ */ + + +/** + * A value to represent littleendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_LIL_ENDIAN + * SDL_Log("This system is littleendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_BIG_ENDIAN + */ #define SDL_LIL_ENDIAN 1234 + +/** + * A value to represent bigendian byteorder. + * + * This is used with the preprocessor macro SDL_BYTEORDER, to determine a + * platform's byte ordering: + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTEORDER + * \sa SDL_LIL_ENDIAN + */ #define SDL_BIG_ENDIAN 4321 + /* @} */ #ifndef SDL_BYTEORDER -#ifdef SDL_PLATFORM_LINUX +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's byte order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_BYTEORDER == SDL_BIG_ENDIAN + * SDL_Log("This system is bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_BYTEORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN +#elif defined(SDL_PLATFORM_LINUX) #include #define SDL_BYTEORDER __BYTE_ORDER #elif defined(SDL_PLATFORM_SOLARIS) @@ -97,8 +169,29 @@ _m_prefetch(void *__P) #endif /* !SDL_BYTEORDER */ #ifndef SDL_FLOATWORDORDER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro that reports the target system's floating point word order. + * + * This is set to either SDL_LIL_ENDIAN or SDL_BIG_ENDIAN (and maybe other + * values in the future, if something else becomes popular). This can be + * tested with the preprocessor, so decisions can be made at compile time. + * + * ```c + * #if SDL_FLOATWORDORDER == SDL_BIG_ENDIAN + * SDL_Log("This system's floats are bigendian."); + * #endif + * ``` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LIL_ENDIAN + * \sa SDL_BIG_ENDIAN + */ +#define SDL_FLOATWORDORDER SDL_LIL_ENDIAN___or_maybe___SDL_BIG_ENDIAN /* predefs from newer gcc versions: */ -#if defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) +#elif defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_BIG_ENDIAN__) && defined(__FLOAT_WORD_ORDER__) #if (__FLOAT_WORD_ORDER__ == __ORDER_LITTLE_ENDIAN__) #define SDL_FLOATWORDORDER SDL_LIL_ENDIAN #elif (__FLOAT_WORD_ORDER__ == __ORDER_BIG_ENDIAN__) @@ -125,10 +218,6 @@ _m_prefetch(void *__P) extern "C" { #endif -/** - * \file SDL_endian.h - */ - /* various modern compilers may have builtin swap */ #if defined(__GNUC__) || defined(__clang__) # define HAS_BUILTIN_BSWAP16 (SDL_HAS_BUILTIN(__builtin_bswap16)) || \ @@ -148,6 +237,7 @@ extern "C" { #endif /* Byte swap 16-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP16 #define SDL_Swap16(x) __builtin_bswap16(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -191,8 +281,10 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) return SDL_static_cast(Uint16, ((x << 8) | (x >> 8))); } #endif +#endif /* Byte swap 32-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP32 #define SDL_Swap32(x) __builtin_bswap32(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -239,8 +331,10 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) ((x >> 8) & 0x0000FF00) | (x >> 24))); } #endif +#endif /* Byte swap 64-bit integer. */ +#ifndef SDL_WIKI_DOCUMENTATION_SECTION #if HAS_BUILTIN_BSWAP64 #define SDL_Swap64(x) __builtin_bswap64(x) #elif (defined(_MSC_VER) && (_MSC_VER >= 1400)) && !defined(__ICL) @@ -290,7 +384,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) return (x); } #endif - +#endif /** * Byte-swap a floating point number. @@ -309,7 +403,7 @@ SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE float SDL_SwapFloat(float x) { @@ -348,7 +442,7 @@ SDL_FORCE_INLINE float SDL_SwapFloat(float x) * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } @@ -369,7 +463,7 @@ SDL_FORCE_INLINE Uint16 SDL_Swap16(Uint16 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } @@ -390,7 +484,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x) { return x_but_byteswapped; } * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } @@ -404,7 +498,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16LE(x) SwapOnlyIfNecessary(x) @@ -418,7 +514,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32LE(x) SwapOnlyIfNecessary(x) @@ -432,7 +530,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64LE(x) SwapOnlyIfNecessary(x) @@ -446,7 +546,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in littleendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x) @@ -460,7 +562,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap16BE(x) SwapOnlyIfNecessary(x) @@ -474,7 +578,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap32BE(x) SwapOnlyIfNecessary(x) @@ -488,7 +594,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_Swap64BE(x) SwapOnlyIfNecessary(x) @@ -502,7 +610,9 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; } * \param x the value to swap, in bigendian byte order. * \returns `x` in native byte order. * - * \since This macro is available since SDL 3.0.0. + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h index a98823f..934967c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_error.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,26 @@ * # CategoryError * * Simple error message routines for SDL. + * + * Most apps will interface with these APIs in exactly one function: when + * almost any SDL function call reports failure, you can get a human-readable + * string of the problem from SDL_GetError(). + * + * These strings are maintained per-thread, and apps are welcome to set their + * own errors, which is popular when building libraries on top of SDL for + * other apps to consume. These strings are set by calling SDL_SetError(). + * + * A common usage pattern is to have a function that returns true for success + * and false for failure, and do this when something fails: + * + * ```c + * if (something_went_wrong) { + * return SDL_SetError("The thing broke in this specific way: %d", errcode); + * } + * ``` + * + * It's also common to just return `false` in this case if the failing thing + * is known to call SDL_SetError(), so errors simply propagate through. */ #ifndef SDL_error_h_ @@ -44,8 +64,8 @@ extern "C" { * * Calling this function will replace any previous error message that was set. * - * This function always returns -1, since SDL frequently uses -1 to signify an - * failing result, leading to this idiom: + * This function always returns false, since SDL frequently uses false to + * signify a failing result, leading to this idiom: * * ```c * if (error_code) { @@ -56,25 +76,49 @@ extern "C" { * \param fmt a printf()-style message format string. * \param ... additional parameters matching % tokens in the `fmt` string, if * any. - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_GetError + * \sa SDL_SetErrorV */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); + +/** + * Set the SDL error message for the current thread. + * + * Calling this function will replace any previous error message that was set. + * + * \param fmt a printf()-style message format string. + * \param ap a variable argument list. + * \returns false. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClearError + * \sa SDL_GetError + * \sa SDL_SetError + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(1); /** * Set an error indicating that memory allocation failed. * * This function does not do any memory allocation. * - * \returns SDL_FALSE. + * \returns false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); +extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); /** * Retrieve a message about the last error that occurred on the current @@ -104,7 +148,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OutOfMemory(void); * or an empty string if there hasn't been an error message set since * the last call to SDL_ClearError(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClearError * \sa SDL_SetError @@ -114,14 +160,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); /** * Clear any previous error message for this thread. * - * \returns SDL_TRUE. + * \returns true. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetError * \sa SDL_SetError */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void); /** * \name Internal error functions @@ -130,8 +178,43 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearError(void); * Private error reporting function - used internally. */ /* @{ */ + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_Unsupported() SDL_SetError("That operation is not supported") + +/** + * A macro to standardize error reporting on unsupported operations. + * + * This simply calls SDL_SetError() with a standardized error string, for + * convenience, consistency, and clarity. + * + * A common usage pattern inside SDL is this: + * + * ```c + * bool MyFunction(const char *str) { + * if (!str) { + * return SDL_InvalidParamError("str"); // returns false. + * } + * DoSomething(str); + * return true; + * } + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) + /* @} *//* Internal error functions */ /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h index fbe2bb0..1323e9f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_events.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,22 +23,50 @@ * # CategoryEvents * * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. */ #ifndef SDL_events_h_ #define SDL_events_h_ +#include #include +#include #include #include #include #include +#include #include #include -#include +#include +#include +#include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -48,29 +76,10 @@ extern "C" { /* General keyboard/mouse/pen state definitions */ -/** - * A value that signifies a button is no longer pressed. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_PRESSED - */ -#define SDL_RELEASED 0 - -/** - * A value that signifies a button has been pressed down. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_RELEASED - */ -#define SDL_PRESSED 1 - - /** * The types of events that can be delivered. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_EventType { @@ -148,7 +157,7 @@ typedef enum SDL_EventType SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */ SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */ SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled - in an event watcher, the window handle is still valid and can still be used to retrieve any userdata + in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid */ SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */ @@ -203,6 +212,7 @@ typedef enum SDL_EventType SDL_EVENT_FINGER_DOWN = 0x700, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, + SDL_EVENT_FINGER_CANCELED, /* 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! */ @@ -243,6 +253,13 @@ typedef enum SDL_EventType /* Render events */ SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */ SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */ + SDL_EVENT_RENDER_DEVICE_LOST, /**< The device has been lost and can't be recovered. */ + + /* Reserved events for private platforms */ + SDL_EVENT_PRIVATE0 = 0x4000, + SDL_EVENT_PRIVATE1, + SDL_EVENT_PRIVATE2, + SDL_EVENT_PRIVATE3, /* Internal events */ SDL_EVENT_POLL_SENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ @@ -265,7 +282,7 @@ typedef enum SDL_EventType /** * Fields shared by every event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CommonEvent { @@ -277,7 +294,7 @@ typedef struct SDL_CommonEvent /** * Display state change event data (event.display.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DisplayEvent { @@ -292,7 +309,7 @@ typedef struct SDL_DisplayEvent /** * Window state change event data (event.window.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_WindowEvent { @@ -307,7 +324,7 @@ typedef struct SDL_WindowEvent /** * Keyboard device event structure (event.kdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_KeyboardDeviceEvent { @@ -326,7 +343,7 @@ typedef struct SDL_KeyboardDeviceEvent * event scancode and modifiers directly from the keyboard layout, bypassing * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_HINT_KEYCODE_OPTIONS @@ -342,8 +359,8 @@ typedef struct SDL_KeyboardEvent SDL_Keycode key; /**< SDL virtual key code */ SDL_Keymod mod; /**< current key modifiers */ Uint16 raw; /**< The platform dependent scancode for this event */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ - Uint8 repeat; /**< Non-zero if this is a key repeat */ + bool down; /**< true if the key is pressed */ + bool repeat; /**< true if this is a key repeat */ } SDL_KeyboardEvent; /** @@ -353,7 +370,7 @@ typedef struct SDL_KeyboardEvent * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingEvent { @@ -369,7 +386,7 @@ typedef struct SDL_TextEditingEvent /** * Keyboard IME candidates event structure (event.edit_candidates.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TextEditingCandidatesEvent { @@ -380,7 +397,10 @@ typedef struct SDL_TextEditingCandidatesEvent const char * const *candidates; /**< The list of candidates, or NULL if there are no candidates available */ Sint32 num_candidates; /**< The number of strings in `candidates` */ Sint32 selected_candidate; /**< The index of the selected candidate, or -1 if no candidate is selected */ - SDL_bool horizontal; /**< SDL_TRUE if the list is horizontal, SDL_FALSE if it's vertical */ + bool horizontal; /**< true if the list is horizontal, false if it's vertical */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_TextEditingCandidatesEvent; /** @@ -389,7 +409,7 @@ typedef struct SDL_TextEditingCandidatesEvent * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput @@ -406,7 +426,7 @@ typedef struct SDL_TextInputEvent /** * Mouse device event structure (event.mdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseDeviceEvent { @@ -419,7 +439,7 @@ typedef struct SDL_MouseDeviceEvent /** * Mouse motion event structure (event.motion.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseMotionEvent { @@ -427,7 +447,7 @@ typedef struct SDL_MouseMotionEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id or SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ SDL_MouseButtonFlags state; /**< The current button state */ float x; /**< X coordinate, relative to window */ float y; /**< Y coordinate, relative to window */ @@ -438,7 +458,7 @@ typedef struct SDL_MouseMotionEvent /** * Mouse button event structure (event.button.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseButtonEvent { @@ -446,9 +466,9 @@ typedef struct SDL_MouseButtonEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 */ Uint8 button; /**< The mouse button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 padding; float x; /**< X coordinate, relative to window */ @@ -458,7 +478,7 @@ typedef struct SDL_MouseButtonEvent /** * Mouse wheel event structure (event.wheel.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MouseWheelEvent { @@ -466,7 +486,7 @@ typedef struct SDL_MouseWheelEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_WindowID windowID; /**< The window with mouse focus, if any */ - SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID */ + SDL_MouseID which; /**< The mouse instance id in relative mode or 0 */ float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */ float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */ SDL_MouseWheelDirection direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */ @@ -477,7 +497,7 @@ typedef struct SDL_MouseWheelEvent /** * Joystick axis motion event structure (event.jaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyAxisEvent { @@ -496,7 +516,7 @@ typedef struct SDL_JoyAxisEvent /** * Joystick trackball motion event structure (event.jball.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBallEvent { @@ -515,7 +535,7 @@ typedef struct SDL_JoyBallEvent /** * Joystick hat position change event structure (event.jhat.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyHatEvent { @@ -538,7 +558,7 @@ typedef struct SDL_JoyHatEvent /** * Joystick button event structure (event.jbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyButtonEvent { @@ -547,7 +567,7 @@ typedef struct SDL_JoyButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The joystick button index */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_JoyButtonEvent; @@ -555,7 +575,12 @@ typedef struct SDL_JoyButtonEvent /** * Joystick device event structure (event.jdevice.*) * - * \since This struct is available since SDL 3.0.0. + * SDL will send JOYSTICK_ADDED events for devices that are already plugged in + * during SDL_Init. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GamepadDeviceEvent */ typedef struct SDL_JoyDeviceEvent { @@ -566,9 +591,9 @@ typedef struct SDL_JoyDeviceEvent } SDL_JoyDeviceEvent; /** - * Joysick battery level change event structure (event.jbattery.*) + * Joystick battery level change event structure (event.jbattery.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_JoyBatteryEvent { @@ -583,7 +608,7 @@ typedef struct SDL_JoyBatteryEvent /** * Gamepad axis motion event structure (event.gaxis.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadAxisEvent { @@ -603,7 +628,7 @@ typedef struct SDL_GamepadAxisEvent /** * Gamepad button event structure (event.gbutton.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadButtonEvent { @@ -612,7 +637,7 @@ typedef struct SDL_GamepadButtonEvent Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_JoystickID which; /**< The joystick instance id */ Uint8 button; /**< The gamepad button (SDL_GamepadButton) */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ Uint8 padding1; Uint8 padding2; } SDL_GamepadButtonEvent; @@ -621,7 +646,16 @@ typedef struct SDL_GamepadButtonEvent /** * Gamepad device event structure (event.gdevice.*) * - * \since This struct is available since SDL 3.0.0. + * Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent + * and an SDL_GamepadDeviceEvent. + * + * SDL will send GAMEPAD_ADDED events for joysticks that are already plugged + * in during SDL_Init() and are recognized as gamepads. It will also send + * events for joysticks that get gamepad mappings at runtime. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_JoyDeviceEvent */ typedef struct SDL_GamepadDeviceEvent { @@ -634,7 +668,7 @@ typedef struct SDL_GamepadDeviceEvent /** * Gamepad touchpad event structure (event.gtouchpad.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadTouchpadEvent { @@ -652,7 +686,7 @@ typedef struct SDL_GamepadTouchpadEvent /** * Gamepad sensor event structure (event.gsensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GamepadSensorEvent { @@ -668,7 +702,7 @@ typedef struct SDL_GamepadSensorEvent /** * Audio device event structure (event.adevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_AudioDeviceEvent { @@ -676,7 +710,7 @@ typedef struct SDL_AudioDeviceEvent Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_AudioDeviceID which; /**< SDL_AudioDeviceID for the device being added or removed or changing */ - Uint8 recording; /**< zero if a playback device, non-zero if a recording device. */ + bool recording; /**< false if a playback device, true if a recording device. */ Uint8 padding1; Uint8 padding2; Uint8 padding3; @@ -685,7 +719,7 @@ typedef struct SDL_AudioDeviceEvent /** * Camera device event structure (event.cdevice.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_CameraDeviceEvent { @@ -695,14 +729,43 @@ typedef struct SDL_CameraDeviceEvent SDL_CameraID which; /**< SDL_CameraID for the device being added or removed or changing */ } SDL_CameraDeviceEvent; + +/** + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_RenderEvent +{ + SDL_EventType type; /**< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST */ + Uint32 reserved; + Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + SDL_WindowID windowID; /**< The window containing the renderer in question. */ +} SDL_RenderEvent; + + /** * Touch finger event structure (event.tfinger.*) * - * \since This struct is available since SDL 3.0.0. + * Coordinates in this event are normalized. `x` and `y` are normalized to a + * range between 0.0f and 1.0f, relative to the window, so (0,0) is the top + * left and (1,1) is the bottom right. Delta coordinates `dx` and `dy` are + * normalized in the ranges of -1.0f (traversed all the way from the bottom or + * right to all the way up or left) to 1.0f (traversed all the way from the + * top or left to all the way down or right). + * + * Note that while the coordinates are _normalized_, they are not _clamped_, + * which means in some circumstances you can get a value outside of this + * range. For example, a renderer using logical presentation might give a + * negative value when the touch is in the letterboxing. Some platforms might + * report a touch outside of the window, which will also be outside of the + * range. + * + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_TouchFingerEvent { - SDL_EventType type; /**< SDL_EVENT_FINGER_MOTION or SDL_EVENT_FINGER_DOWN or SDL_EVENT_FINGER_UP */ + SDL_EventType type; /**< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ SDL_TouchID touchID; /**< The touch device id */ @@ -728,14 +791,14 @@ typedef struct SDL_TouchFingerEvent * is there." The pen touching and lifting off from the tablet while not * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenProximityEvent { SDL_EventType type; /**< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ } SDL_PenProximityEvent; @@ -748,18 +811,18 @@ typedef struct SDL_PenProximityEvent * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when * dealing with pen motion. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenMotionEvent { SDL_EventType type; /**< SDL_EVENT_PEN_MOTION */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ - SDL_WindowID windowID; /**< The window with mouse focus, if any */ + SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ } SDL_PenMotionEvent; /** @@ -768,7 +831,7 @@ typedef struct SDL_PenMotionEvent * These events come when a pen touches a surface (a tablet, etc), or lifts * off from one. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenTouchEvent { @@ -778,10 +841,10 @@ typedef struct SDL_PenTouchEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ - Uint8 eraser; /**< Non-zero if eraser end is used (not all pens support this). */ - Uint8 state; /**< SDL_PRESSED (pen is touching) or SDL_RELEASED (pen is lifted off) */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ + bool eraser; /**< true if eraser end is used (not all pens support this). */ + bool down; /**< true if the pen is touching or false if the pen is lifted off */ } SDL_PenTouchEvent; /** @@ -790,7 +853,7 @@ typedef struct SDL_PenTouchEvent * This is for buttons on the pen itself that the user might click. The pen * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenButtonEvent { @@ -800,10 +863,10 @@ typedef struct SDL_PenButtonEvent SDL_WindowID windowID; /**< The window with mouse focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ Uint8 button; /**< The pen button index (first button is 1). */ - Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */ + bool down; /**< true if the button is pressed */ } SDL_PenButtonEvent; /** @@ -812,7 +875,7 @@ typedef struct SDL_PenButtonEvent * You might get some of these events even if the pen isn't touching the * tablet. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PenAxisEvent { @@ -822,8 +885,8 @@ typedef struct SDL_PenAxisEvent SDL_WindowID windowID; /**< The window with pen focus, if any */ SDL_PenID which; /**< The pen instance id */ SDL_PenInputFlags pen_state; /**< Complete pen input state at time of event */ - float x; /**< X position of pen on tablet */ - float y; /**< Y position of pen on tablet */ + float x; /**< X coordinate, relative to window */ + float y; /**< Y coordinate, relative to window */ SDL_PenAxis axis; /**< Axis that has changed */ float value; /**< New value of axis */ } SDL_PenAxisEvent; @@ -832,7 +895,7 @@ typedef struct SDL_PenAxisEvent * An event used to drop text or request a file open by the system * (event.drop.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DropEvent { @@ -850,19 +913,22 @@ typedef struct SDL_DropEvent * An event triggered when the clipboard contents have changed * (event.clipboard.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_ClipboardEvent { SDL_EventType type; /**< SDL_EVENT_CLIPBOARD_UPDATE */ Uint32 reserved; Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */ + bool owner; /**< are we owning the clipboard (internal update) */ + Sint32 num_mime_types; /**< number of mime types */ + const char **mime_types; /**< current mime types */ } SDL_ClipboardEvent; /** * Sensor event structure (event.sensor.*) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_SensorEvent { @@ -877,7 +943,7 @@ typedef struct SDL_SensorEvent /** * The "quit requested" event * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_QuitEvent { @@ -895,7 +961,7 @@ typedef struct SDL_QuitEvent * the programmer; the only requirement is that '''type''' is a value obtained * from SDL_RegisterEvents(). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_UserEvent { @@ -912,7 +978,10 @@ typedef struct SDL_UserEvent /** * The structure for all events in SDL. * - * \since This struct is available since SDL 3.0.0. + * The SDL_Event structure is the core of all event handling in SDL. SDL_Event + * is a union of all event structures used in SDL. + * + * \since This struct is available since SDL 3.2.0. */ typedef union SDL_Event { @@ -951,6 +1020,7 @@ typedef union SDL_Event SDL_PenMotionEvent pmotion; /**< Pen motion event data */ SDL_PenButtonEvent pbutton; /**< Pen button event data */ SDL_PenAxisEvent paxis; /**< Pen axis event data */ + SDL_RenderEvent render; /**< Render event data */ SDL_DropEvent drop; /**< Drag and drop event data */ SDL_ClipboardEvent clipboard; /**< Clipboard event data */ @@ -981,10 +1051,6 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * * This function updates the event queue and internal input device state. * - * **WARNING**: This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider only doing those - * things on the main thread in any case. - * * SDL_PumpEvents() gathers all the pending input information from devices and * places it in the event queue. Without calls to SDL_PumpEvents() no events * would ever be placed on the queue. Often the need for calls to @@ -993,7 +1059,9 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL * polling or waiting for events (e.g. you are filtering them), then you must * call SDL_PumpEvents() to force an event queue update. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent @@ -1001,11 +1069,17 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern SDL_DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ + +/** + * The type of action to request from SDL_PeepEvents(). + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_EventAction { - SDL_ADDEVENT, - SDL_PEEKEVENT, - SDL_GETEVENT + SDL_ADDEVENT, /**< Add events to the back of the queue. */ + SDL_PEEKEVENT, /**< Check but don't remove events from the queue front. */ + SDL_GETEVENT /**< Retrieve/remove events from the front of the queue. */ } SDL_EventAction; /** @@ -1017,7 +1091,9 @@ typedef enum SDL_EventAction * event queue. * - `SDL_PEEKEVENT`: `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the - * caller and will _not_ be removed from the queue. + * caller and will _not_ be removed from the queue. If you pass NULL for + * `events`, then `numevents` is ignored and the total number of matching + * events will be returned. * - `SDL_GETEVENT`: up to `numevents` events at the front of the event queue, * within the specified minimum and maximum type, will be returned to the * caller and will be removed from the queue. @@ -1026,8 +1102,6 @@ typedef enum SDL_EventAction * Otherwise, the events may not be ready to be filtered when you call * SDL_PeepEvents(). * - * This function is thread-safe. - * * \param events destination buffer for the retrieved events, may be NULL to * leave the events in the queue and return the number of events * that would have been stored. @@ -1042,7 +1116,9 @@ typedef enum SDL_EventAction * \returns the number of events actually stored or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PumpEvents @@ -1058,14 +1134,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, * instead. * * \param type the type of event to be queried; see SDL_EventType for details. - * \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if - * events matching `type` are not present. + * \returns true if events matching `type` are present, or false if events + * matching `type` are not present. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type); /** @@ -1077,14 +1155,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type); * SDL_EventType for details. * \param maxType the high end of event type to be queried, inclusive; see * SDL_EventType for details. - * \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are - * present, or SDL_FALSE if not. + * \returns true if events with type >= `minType` and <= `maxType` are + * present, or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); +extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); /** * Clear events of a specific type from the event queue. @@ -1106,7 +1186,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxTyp * * \param type the type of event to be cleared; see SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvents */ @@ -1131,7 +1213,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type); * \param maxType the high end of event type to be cleared, inclusive; see * SDL_EventType for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvent */ @@ -1171,16 +1255,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType) * * \param event the SDL_Event structure to be filled with the next event from * the queue, or NULL. - * \returns SDL_TRUE if this got an event or SDL_FALSE if there are none - * available. + * \returns true if this got an event or false if there are none available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent * \sa SDL_WaitEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event); /** * Wait indefinitely for the next available event. @@ -1193,16 +1278,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event); * * \param event the SDL_Event structure to be filled in with the next event * from the queue, or NULL. - * \returns SDL_TRUE on success or SDL_FALSE if there was an error while - * waiting for events; call SDL_GetError() for more information. + * \returns true on success or false if there was an error while waiting for + * events; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEventTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event); /** * Wait until the specified timeout (in milliseconds) for the next available @@ -1221,16 +1308,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event); * from the queue, or NULL. * \param timeoutMS the maximum number of milliseconds to wait for the next * available event. - * \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed - * without any events available. + * \returns true if this got an event or false if the timeout elapsed without + * any events available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent * \sa SDL_WaitEvent */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS); /** * Add an event to the event queue. @@ -1244,8 +1333,6 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * Note: Pushing device input events onto the queue doesn't modify the state * of the device within SDL. * - * This function is thread-safe, and can be called from other threads safely. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter but events added with SDL_PeepEvents() do not. * @@ -1254,17 +1341,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint * its own custom event types. * * \param event the SDL_Event to be added to the queue. - * \returns SDL_TRUE on success, SDL_FALSE if the event was filtered or on - * failure; call SDL_GetError() for more information. A common reason - * for error is the event queue being full. + * \returns true on success, false if the event was filtered or on failure; + * call SDL_GetError() for more information. A common reason for + * error is the event queue being full. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PeepEvents * \sa SDL_PollEvent * \sa SDL_RegisterEvents */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_PushEvent(SDL_Event *event); /** * A function pointer used for callbacks that watch the event queue. @@ -1272,29 +1361,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PushEvent(SDL_Event *event); * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or * SDL_AddEventWatch, etc. * \param event the event that triggered the callback. - * \returns SDL_TRUE to permit event to be added to the queue, and SDL_FALSE - * to disallow it. When used with SDL_AddEventWatch, the return value - * is ignored. + * \returns true to permit event to be added to the queue, and false to + * disallow it. When used with SDL_AddEventWatch, the return value is + * ignored. * * \threadsafety SDL may call this callback at any time from any thread; the * application is responsible for locking resources the callback * touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetEventFilter * \sa SDL_AddEventWatch */ -typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); +typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); /** - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. * - * If the filter function returns SDL_TRUE when called, then the event will be - * added to the internal queue. If it returns SDL_FALSE, then the event will - * be dropped from the queue, but the internal state will still be updated. - * This allows selective filtering of dynamically arriving events. + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. + * + * If the filter function returns true when called, then the event will be + * added to the internal queue. If it returns false, then the event will be + * dropped from the queue, but the internal state will still be updated. This + * allows selective filtering of dynamically arriving events. * * **WARNING**: Be very careful of what you do in the event filter function, * as it may run in a different thread! @@ -1303,17 +1395,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. @@ -1321,11 +1405,9 @@ typedef SDL_bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event); * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \threadsafety SDL may call the filter callback at any time from any thread; - * the application is responsible for locking resources the - * callback touches that need to be protected. + * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch * \sa SDL_SetEventEnabled @@ -1344,13 +1426,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void * \param filter the current callback function will be stored here. * \param userdata the pointer that is passed to the current event filter will * be stored here. - * \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set. + * \returns true on success or false if there is no event filter set. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata); /** * Add a callback to be triggered when an event is added to the event queue. @@ -1372,17 +1456,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, * * \param filter an SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata); /** * Remove an event watch callback added with SDL_AddEventWatch(). @@ -1393,7 +1477,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, v * \param filter the function originally passed to SDL_AddEventWatch(). * \param userdata the pointer originally passed to SDL_AddEventWatch(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -1401,7 +1487,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo /** * Run a specific filter function on the current event queue, removing any - * events for which the filter returns SDL_FALSE. + * events for which the filter returns false. * * See SDL_SetEventFilter() for more information. Unlike SDL_SetEventFilter(), * this function does not change the filter permanently, it only uses the @@ -1410,7 +1496,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo * \param filter the SDL_EventFilter function to call when an event happens. * \param userdata a pointer that is passed to `filter`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetEventFilter * \sa SDL_SetEventFilter @@ -1423,23 +1511,27 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void * * \param type the type of event; see SDL_EventType for details. * \param enabled whether to process the event or not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EventEnabled */ -extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled); /** * Query the state of processing events by type. * * \param type the type of event; see SDL_EventType for details. - * \returns SDL_TRUE if the event is being processed, SDL_FALSE otherwise. + * \returns true if the event is being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); +extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type); /** * Allocate a set of user-defined events, and return the beginning event @@ -1449,7 +1541,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); * \returns the beginning event number, or 0 if numevents is invalid or if * there are not enough user-defined events left. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent */ @@ -1461,7 +1555,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); * \param event an event containing a `windowID`. * \returns the associated window on success or NULL if there is none. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h index 5faa244..af3ca27 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_filesystem.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,23 @@ /** * # CategoryFilesystem * - * SDL Filesystem API. + * SDL offers an API for examining and manipulating the system's filesystem. + * This covers most things one would need to do with directories, except for + * actual file I/O (which is covered by [CategoryIOStream](CategoryIOStream) + * and [CategoryAsyncIO](CategoryAsyncIO) instead). + * + * There are functions to answer necessary path questions: + * + * - Where is my app's data? SDL_GetBasePath(). + * - Where can I safely write files? SDL_GetPrefPath(). + * - Where are paths like Downloads, Desktop, Music? SDL_GetUserFolder(). + * - What is this thing at this location? SDL_GetPathInfo(). + * - What items live in this folder? SDL_EnumerateDirectory(). + * - What items live in this folder by wildcard? SDL_GlobDirectory(). + * - What is my current working directory? SDL_GetCurrentDirectory(). + * + * SDL also offers functions to manipulate the directory tree: renaming, + * removing, copying files. */ #ifndef SDL_filesystem_h_ @@ -73,7 +89,7 @@ extern "C" { * doesn't implement this functionality, call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPrefPath */ @@ -128,7 +144,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); * etc.). This should be freed with SDL_free() when it is no longer * needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBasePath */ @@ -143,66 +159,40 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrefPath(const char *org, const char * * * The folders supported per platform are: * - * | | Windows | WinRT/UWP |macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | - * | ----------- | ------- | --------- |--------- | ---- | ---------- | ----- | ---------- | - * | HOME | X | X | X | | X | X | X | - * | DESKTOP | X | X | X | | X | X | | - * | DOCUMENTS | X | X | X | | X | | | - * | DOWNLOADS | Vista+ | X | X | | X | | | - * | MUSIC | X | X | X | | X | | | - * | PICTURES | X | X | X | | X | | | - * | PUBLICSHARE | | | X | | X | | | - * | SAVEDGAMES | Vista+ | | | | | | | - * | SCREENSHOTS | Vista+ | X | | | | | | - * | TEMPLATES | X | X | X | | X | | | - * | VIDEOS | X | X | X* | | X | | | + * | | Windows | macOS/iOS | tvOS | Unix (XDG) | Haiku | Emscripten | + * | ----------- | ------- | --------- | ---- | ---------- | ----- | ---------- | + * | HOME | X | X | | X | X | X | + * | DESKTOP | X | X | | X | X | | + * | DOCUMENTS | X | X | | X | | | + * | DOWNLOADS | Vista+ | X | | X | | | + * | MUSIC | X | X | | X | | | + * | PICTURES | X | X | | X | | | + * | PUBLICSHARE | | X | | X | | | + * | SAVEDGAMES | Vista+ | | | | | | + * | SCREENSHOTS | Vista+ | | | | | | + * | TEMPLATES | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | * * Note that on macOS/iOS, the Videos folder is called "Movies". * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetUserFolder */ typedef enum SDL_Folder { - /** The folder which contains all of the current user's data, preferences, - and documents. It usually contains most of the other folders. If a - requested folder does not exist, the home folder can be considered a safe - fallback to store a user's documents. */ - SDL_FOLDER_HOME, - /** The folder of files that are displayed on the desktop. Note that the - existence of a desktop folder does not guarantee that the system does - show icons on its desktop; certain GNU/Linux distros with a graphical - environment may not have desktop icons. */ - SDL_FOLDER_DESKTOP, - /** User document files, possibly application-specific. This is a good - place to save a user's projects. */ - SDL_FOLDER_DOCUMENTS, - /** Standard folder for user files downloaded from the internet. */ - SDL_FOLDER_DOWNLOADS, - /** Music files that can be played using a standard music player (mp3, - ogg...). */ - SDL_FOLDER_MUSIC, - /** Image files that can be displayed using a standard viewer (png, - jpg...). */ - SDL_FOLDER_PICTURES, - /** Files that are meant to be shared with other users on the same - computer. */ - SDL_FOLDER_PUBLICSHARE, - /** Save files for games. */ - SDL_FOLDER_SAVEDGAMES, - /** Application screenshots. */ - SDL_FOLDER_SCREENSHOTS, - /** Template files to be used when the user requests the desktop environment - to create a new file in a certain folder, such as "New Text File.txt". - Any file in the Templates folder can be used as a starting point for a - new file. */ - SDL_FOLDER_TEMPLATES, - /** Video files that can be played using a standard video player (mp4, - webm...). */ - SDL_FOLDER_VIDEOS, - /** total number of types in this enum, not a folder type by itself. */ - SDL_FOLDER_TOTAL + SDL_FOLDER_HOME, /**< The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a requested folder does not exist, the home folder can be considered a safe fallback to store a user's documents. */ + SDL_FOLDER_DESKTOP, /**< The folder of files that are displayed on the desktop. Note that the existence of a desktop folder does not guarantee that the system does show icons on its desktop; certain GNU/Linux distros with a graphical environment may not have desktop icons. */ + SDL_FOLDER_DOCUMENTS, /**< User document files, possibly application-specific. This is a good place to save a user's projects. */ + SDL_FOLDER_DOWNLOADS, /**< Standard folder for user files downloaded from the internet. */ + SDL_FOLDER_MUSIC, /**< Music files that can be played using a standard music player (mp3, ogg...). */ + SDL_FOLDER_PICTURES, /**< Image files that can be displayed using a standard viewer (png, jpg...). */ + SDL_FOLDER_PUBLICSHARE, /**< Files that are meant to be shared with other users on the same computer. */ + SDL_FOLDER_SAVEDGAMES, /**< Save files for games. */ + SDL_FOLDER_SCREENSHOTS, /**< Application screenshots. */ + SDL_FOLDER_TEMPLATES, /**< Template files to be used when the user requests the desktop environment to create a new file in a certain folder, such as "New Text File.txt". Any file in the Templates folder can be used as a starting point for a new file. */ + SDL_FOLDER_VIDEOS, /**< Video files that can be played using a standard video player (mp4, webm...). */ + SDL_FOLDER_COUNT /**< Total number of types in this enum, not a folder type by itself. */ } SDL_Folder; /** @@ -226,13 +216,24 @@ typedef enum SDL_Folder * \returns either a null-terminated C string containing the full path to the * folder, or NULL if an error happened. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder); /* Abstract filesystem interface */ +/** + * Types of filesystem entries. + * + * Note that there may be other sorts of items on a filesystem: devices, + * symlinks, named pipes, etc. They are currently reported as + * SDL_PATHTYPE_OTHER. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_PathInfo + */ typedef enum SDL_PathType { SDL_PATHTYPE_NONE, /**< path does not exist */ @@ -241,19 +242,27 @@ typedef enum SDL_PathType SDL_PATHTYPE_OTHER /**< something completely different like a device node (not a symlink, those are always followed) */ } SDL_PathType; +/** + * Information about a path on the filesystem. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetPathInfo + * \sa SDL_GetStoragePathInfo + */ typedef struct SDL_PathInfo { - SDL_PathType type; /* the path type */ - Uint64 size; /* the file size in bytes */ - SDL_Time create_time; /* the time when the path was created */ - SDL_Time modify_time; /* the last time the path was modified */ - SDL_Time access_time; /* the last time the path was read */ + SDL_PathType type; /**< the path type */ + Uint64 size; /**< the file size in bytes */ + SDL_Time create_time; /**< the time when the path was created */ + SDL_Time modify_time; /**< the last time the path was modified */ + SDL_Time access_time; /**< the last time the path was read */ } SDL_PathInfo; /** - * Flags for path matching + * Flags for path matching. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GlobDirectory * \sa SDL_GlobStorageDirectory @@ -263,73 +272,160 @@ typedef Uint32 SDL_GlobFlags; #define SDL_GLOB_CASEINSENSITIVE (1u << 0) /** - * Create a directory. + * Create a directory, and any missing parent directories. + * + * This reports success if `path` already exists as a directory. + * + * If parent directories are missing, it will also create them. Note that if + * this fails, it will not remove any parent directories it already made. * * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateDirectory(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateDirectory(const char *path); -/* Callback for directory enumeration. Return 1 to keep enumerating, - 0 to stop enumerating (no error), -1 to stop enumerating and - report an error. `dirname` is the directory being enumerated, - `fname` is the enumerated entry. */ -typedef int (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); +/** + * Possible results from an enumeration callback. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectoryCallback + */ +typedef enum SDL_EnumerationResult +{ + SDL_ENUM_CONTINUE, /**< Value that requests that enumeration continue. */ + SDL_ENUM_SUCCESS, /**< Value that requests that enumeration stop, successfully. */ + SDL_ENUM_FAILURE /**< Value that requests that enumeration stop, as a failure. */ +} SDL_EnumerationResult; + +/** + * Callback for directory enumeration. + * + * Enumeration of directory entries will continue until either all entries + * have been provided to the callback, or the callback has requested a stop + * through its return value. + * + * Returning SDL_ENUM_CONTINUE will let enumeration proceed, calling the + * callback with further entries. SDL_ENUM_SUCCESS and SDL_ENUM_FAILURE will + * terminate the enumeration early, and dictate the return value of the + * enumeration function itself. + * + * `dirname` is guaranteed to end with a path separator ('\\' on Windows, '/' + * on most other platforms). + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param dirname the directory that is being enumerated. + * \param fname the next entry in the enumeration. + * \returns how the enumeration should proceed. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EnumerateDirectory + */ +typedef SDL_EnumerationResult (SDLCALL *SDL_EnumerateDirectoryCallback)(void *userdata, const char *dirname, const char *fname); /** * Enumerate a directory through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. * * \param path the path of the directory to enumerate. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateDirectory(const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory. * - * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Directories that are not empty will fail; this function will not recursely + * delete directory trees. * - * \since This function is available since SDL 3.0.0. + * \param path the path to remove from the filesystem. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemovePath(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemovePath(const char *path); /** * Rename a file or directory. * + * If the file at `newpath` already exists, it will replaced. + * + * Note that this will not copy files across filesystems/drives/volumes, as + * that is a much more complicated (and possibly time-consuming) operation. + * + * Which is to say, if this function fails, SDL_CopyFile() to a temporary file + * in the same directory as `newpath`, then SDL_RenamePath() from the + * temporary file to `newpath` and SDL_RemovePath() on `oldpath` might work + * for files. Renaming a non-empty directory across filesystems is + * dramatically more complex, however. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenamePath(const char *oldpath, const char *newpath); /** * Copy a file. * + * If the file at `newpath` already exists, it will be overwritten with the + * contents of the file at `oldpath`. + * + * This function will block until the copy is complete, which might be a + * significant time for large files on slow disks. On some platforms, the copy + * can be handed off to the OS itself, but on others SDL might just open both + * paths, and read from one and write to the other. + * + * Note that this is not an atomic operation! If something tries to read from + * `newpath` while the copy is in progress, it will see an incomplete copy of + * the data, and if the calling thread terminates (or the power goes out) + * during the copy, `newpath`'s previous contents will be gone, replaced with + * an incomplete copy of the data. To avoid this risk, it is recommended that + * the app copy to a temporary file in the same directory as `newpath`, and if + * the copy is successful, use SDL_RenamePath() to replace `newpath` with the + * temporary file. This will ensure that reads of `newpath` will either see a + * complete copy of the data, or it will see the pre-copy state of `newpath`. + * + * This function attempts to synchronize the newly-copied data to disk before + * returning, if the platform allows it, so that the renaming trick will not + * have a problem in a system crash or power failure, where the file could be + * renamed but the contents never made it from the system file cache to the + * physical disk. + * + * If the copy fails for any reason, the state of `newpath` is undefined. It + * might be half a copy, it might be the untouched data of what was already + * there, or it might be a zero-byte file, etc. + * * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyFile(const char *oldpath, const char *newpath); /** * Get information about a filesystem path. @@ -337,21 +433,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyFile(const char *oldpath, const cha * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *info); /** * Enumerate a directory tree, filtered by pattern, and return a list. * * Files are filtered out if they don't match the string in `pattern`, which - * may contain wildcard characters '*' (match everything) and '?' (match one + * may contain wildcard characters '\*' (match everything) and '?' (match one * character). If pattern is NULL, no filtering is done and all results are * returned. Subdirectories are permitted, and are specified with a path - * separator of '/'. Wildcard characters '*' and '?' never match a path + * separator of '/'. Wildcard characters '\*' and '?' never match a path * separator. * * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching @@ -373,10 +469,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetPathInfo(const char *path, SDL_PathI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count); +/** + * Get what the system believes is the "current working directory." + * + * For systems without a concept of a current working directory, this will + * still attempt to provide something reasonable. + * + * SDL does not provide a means to _change_ the current working directory; for + * platforms without this concept, this would cause surprises with file access + * outside of SDL. + * + * The returned path is guaranteed to end with a path separator ('\\' on + * Windows, '/' on most other platforms). + * + * \returns a UTF-8 string of the current working directory in + * platform-dependent notation. NULL if there's a problem. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_GetCurrentDirectory(void); + /* Ends C function definitions when using C++ */ #ifdef __cplusplus } diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h index 3d2d726..264f763 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gamepad.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,6 +51,24 @@ * If you would like to receive gamepad updates while the application is in * the background, you should set the following hint before calling * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. */ #ifndef SDL_gamepad_h_ @@ -58,9 +76,11 @@ #include #include -#include -#include +#include #include +#include +#include +#include #include #include @@ -72,7 +92,7 @@ extern "C" { /** * The structure used to identify an SDL gamepad * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Gamepad SDL_Gamepad; @@ -98,7 +118,7 @@ typedef enum SDL_GamepadType SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT, SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR, - SDL_GAMEPAD_TYPE_MAX + SDL_GAMEPAD_TYPE_COUNT } SDL_GamepadType; /** @@ -122,15 +142,15 @@ typedef enum SDL_GamepadType * You can query the labels for the face buttons using * SDL_GetGamepadButtonLabel() * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButton { SDL_GAMEPAD_BUTTON_INVALID = -1, - SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */ - SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */ - SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */ - SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */ + SDL_GAMEPAD_BUTTON_SOUTH, /**< Bottom face button (e.g. Xbox A button) */ + SDL_GAMEPAD_BUTTON_EAST, /**< Right face button (e.g. Xbox B button) */ + SDL_GAMEPAD_BUTTON_WEST, /**< Left face button (e.g. Xbox X button) */ + SDL_GAMEPAD_BUTTON_NORTH, /**< Top face button (e.g. Xbox Y button) */ SDL_GAMEPAD_BUTTON_BACK, SDL_GAMEPAD_BUTTON_GUIDE, SDL_GAMEPAD_BUTTON_START, @@ -142,18 +162,18 @@ typedef enum SDL_GamepadButton SDL_GAMEPAD_BUTTON_DPAD_DOWN, SDL_GAMEPAD_BUTTON_DPAD_LEFT, SDL_GAMEPAD_BUTTON_DPAD_RIGHT, - SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ - SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ - SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ - SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */ - SDL_GAMEPAD_BUTTON_MISC2, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC3, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC4, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC5, /* Additional button */ - SDL_GAMEPAD_BUTTON_MISC6, /* Additional button */ - SDL_GAMEPAD_BUTTON_MAX + SDL_GAMEPAD_BUTTON_MISC1, /**< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /**< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /**< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */ + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /**< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */ + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /**< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */ + SDL_GAMEPAD_BUTTON_TOUCHPAD, /**< PS4/PS5 touchpad button */ + SDL_GAMEPAD_BUTTON_MISC2, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC3, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC4, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC5, /**< Additional button */ + SDL_GAMEPAD_BUTTON_MISC6, /**< Additional button */ + SDL_GAMEPAD_BUTTON_COUNT } SDL_GamepadButton; /** @@ -165,7 +185,7 @@ typedef enum SDL_GamepadButton * For a complete set, you should look at the button and gamepad type and have * a set of symbols that work well with your art style. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadButtonLabel { @@ -192,7 +212,7 @@ typedef enum SDL_GamepadButtonLabel * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the * same range that will be reported by the lower-level SDL_GetJoystickAxis(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadAxis { @@ -203,7 +223,7 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_RIGHTY, SDL_GAMEPAD_AXIS_LEFT_TRIGGER, SDL_GAMEPAD_AXIS_RIGHT_TRIGGER, - SDL_GAMEPAD_AXIS_MAX + SDL_GAMEPAD_AXIS_COUNT } SDL_GamepadAxis; /** @@ -214,7 +234,7 @@ typedef enum SDL_GamepadAxis * gamepad. This enum is used as part of SDL_GamepadBinding to specify those * mappings. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_GamepadBindingType { @@ -235,7 +255,7 @@ typedef enum SDL_GamepadBindingType * more with a simple text string. Those strings are parsed into a collection * of these structs to make it easier to operate on the data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetGamepadBindings */ @@ -293,6 +313,9 @@ typedef struct SDL_GamepadBinding * * Buttons can be used as a gamepad axes and vice versa. * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * * This string shows an example of a valid mapping for a gamepad: * * ```c @@ -305,10 +328,15 @@ typedef struct SDL_GamepadBinding * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); @@ -321,6 +349,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -330,21 +361,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); * constrained environment. * * \param src the data stream for the mappings to be added. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the number of mappings added or -1 on failure; call SDL_GetError() * for more information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromFile * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ -extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); /** * Load a set of gamepad mappings from a file. @@ -355,6 +389,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * If a new mapping is loaded for an already known gamepad GUID, the later * version will overwrite the one currently loaded. * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * * Mappings not belonging to the current platform or with no platform field * specified will be ignored (i.e. mappings for Linux will be ignored in * Windows, etc). @@ -365,12 +402,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMappingsFromIO * \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED */ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); @@ -379,12 +419,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file) * * This will generate gamepad events as needed if device mappings change. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. @@ -396,7 +436,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReloadGamepadMappings(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); @@ -408,7 +448,7 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); * information. This should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUID @@ -425,7 +465,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid); * available; call SDL_GetError() for more information. This should * be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMappingForID @@ -442,26 +482,26 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad); * \param instance_id the joystick instance ID. * \param mapping the mapping to use for this device, or NULL to clear the * mapping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddGamepadMapping * \sa SDL_GetGamepadMapping */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_id, const char *mapping); /** * Return whether a gamepad is currently connected. * - * \returns SDL_TRUE if a gamepad is connected, SDL_FALSE otherwise. + * \returns true if a gamepad is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. @@ -472,7 +512,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasGamepad * \sa SDL_OpenGamepad @@ -483,15 +523,15 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count); * Check if the given joystick is supported by the gamepad interface. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the given joystick is supported by the gamepad - * interface, SDL_FALSE if it isn't or it's an invalid index. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks * \sa SDL_OpenGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); /** * Get the implementation dependent name of a gamepad. @@ -502,7 +542,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); * \returns the name of the selected gamepad. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadName * \sa SDL_GetGamepads @@ -518,7 +558,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID * \returns the path of the selected gamepad. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPath * \sa SDL_GetGamepads @@ -533,7 +573,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepads @@ -549,7 +589,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID in * \returns the GUID of the selected gamepad. If called on an invalid index, * this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString * \sa SDL_GetGamepads @@ -566,7 +606,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID inst * \returns the USB vendor ID of the selected gamepad. If called on an invalid * index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendor * \sa SDL_GetGamepads @@ -583,7 +623,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID inst * \returns the USB product ID of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProduct * \sa SDL_GetGamepads @@ -600,7 +640,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID ins * \returns the product version of the selected gamepad. If called on an * invalid index, this function returns zero. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersion * \sa SDL_GetGamepads @@ -615,7 +655,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_Joystic * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadType * \sa SDL_GetGamepads @@ -631,7 +671,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_Joystick * \param instance_id the joystick instance ID. * \returns the gamepad type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepads @@ -648,7 +688,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys * \returns the mapping string. Returns NULL if no mapping is available. This * should be freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepads * \sa SDL_GetGamepadMapping @@ -662,7 +702,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID ins * \returns a gamepad identifier or NULL if an error occurred; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseGamepad * \sa SDL_IsGamepad @@ -677,7 +717,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instanc * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); @@ -687,7 +727,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID in * \param player_index the player index, which different from the instance ID. * \returns the SDL_Gamepad associated with a player index. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex * \sa SDL_SetGamepadPlayerIndex @@ -717,7 +757,7 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int play * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); @@ -735,7 +775,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa * \returns the instance ID of the specified gamepad on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); @@ -747,7 +787,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad * \returns the implementation dependent name for the gamepad, or NULL if * there is no name or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadNameForID */ @@ -761,7 +801,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad * \returns the implementation dependent path for the gamepad, or NULL if * there is no path or the identifier passed is invalid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPathForID */ @@ -774,7 +814,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeForID */ @@ -787,7 +827,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRealGamepadTypeForID */ @@ -801,7 +841,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad * * \param gamepad the gamepad object to query. * \returns the player index for gamepad, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadPlayerIndex */ @@ -813,14 +853,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to adjust. * \param player_index player index to assign to this gamepad, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index); /** * Get the USB vendor ID of an opened gamepad, if available. @@ -830,7 +870,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *game * \param gamepad the gamepad object to query. * \returns the USB vendor ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadVendorForID */ @@ -844,7 +884,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product ID, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductForID */ @@ -858,7 +898,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad); * \param gamepad the gamepad object to query. * \returns the USB product version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadProductVersionForID */ @@ -872,7 +912,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gam * \param gamepad the gamepad object to query. * \returns the gamepad firmware version, or zero if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); @@ -884,7 +924,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga * \param gamepad the gamepad object to query. * \returns the serial number, or NULL if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); @@ -897,7 +937,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamep * \param gamepad the gamepad object to query. * \returns the gamepad handle, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); @@ -909,7 +949,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepa * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); @@ -929,7 +969,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnection * battery. * \returns the current battery state. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); @@ -938,12 +978,12 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad * * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). - * \returns SDL_TRUE if the gamepad has been opened and is currently - * connected, or SDL_FALSE if not. + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** * Get the underlying joystick from a gamepad. @@ -961,7 +1001,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); @@ -973,12 +1013,12 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g * * \param enabled whether to process gamepad events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadEventsEnabled * \sa SDL_UpdateGamepads */ -extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled); /** * Query the state of gamepad event processing. @@ -986,14 +1026,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself * and check the state of the gamepad when you want gamepad information. * - * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE - * otherwise. + * \returns true if gamepad events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void); /** * Get the SDL joystick layer bindings for a gamepad. @@ -1005,7 +1044,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); @@ -1016,7 +1055,7 @@ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gam * enabled. Under such circumstances, it will not be necessary to call this * function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); @@ -1032,7 +1071,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); * \returns the SDL_GamepadType enum corresponding to the input string, or * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForType */ @@ -1046,7 +1085,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTypeFromString */ @@ -1068,7 +1107,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_Gamepad * \returns the SDL_GamepadAxis enum corresponding to the input string, or * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForAxis */ @@ -1082,7 +1121,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAxisFromString */ @@ -1096,14 +1135,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad * * \param gamepad a gamepad. * \param axis an axis enum value (an SDL_GamepadAxis value). - * \returns SDL_TRUE if the gamepad has this axis, SDL_FALSE otherwise. + * \returns true if the gamepad has this axis, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis); /** * Get the current state of an axis control on a gamepad. @@ -1122,7 +1161,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SD * \returns axis state (including 0) on success or 0 (also) on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis * \sa SDL_GetGamepadButton @@ -1141,7 +1180,7 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_ * \returns the SDL_GamepadButton enum corresponding to the input string, or * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadStringForButton */ @@ -1155,7 +1194,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con * specified. The string returned is of the format used by * SDL_Gamepad mapping strings. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonFromString */ @@ -1169,28 +1208,27 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep * * \param gamepad a gamepad. * \param button a button enum value (an SDL_GamepadButton value). - * \returns SDL_TRUE if the gamepad has this button, SDL_FALSE otherwise. + * \returns true if the gamepad has this button, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasAxis */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the current state of a button on a gamepad. * * \param gamepad a gamepad. * \param button a button index (one of the SDL_GamepadButton values). - * \returns 1 for pressed state or 0 for not pressed state or failure; call - * SDL_GetError() for more information. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasButton * \sa SDL_GetGamepadAxis */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); /** * Get the label of a button on a gamepad. @@ -1199,7 +1237,7 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabel */ @@ -1212,7 +1250,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT * \param button a button index (one of the SDL_GamepadButton values). * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadButtonLabelForType */ @@ -1224,7 +1262,7 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL * \param gamepad a gamepad. * \returns number of touchpads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ @@ -1238,7 +1276,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad) * \param touchpad a touchpad. * \returns number of supported simultaneous fingers. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadTouchpadFinger * \sa SDL_GetNumGamepadTouchpads @@ -1251,35 +1289,36 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga * \param gamepad a gamepad. * \param touchpad a touchpad. * \param finger a finger. - * \param state filled with state. - * \param x filled with x position, normalized 0 to 1, with the origin in the - * upper left. - * \param y filled with y position, normalized 0 to 1, with the origin in the - * upper left. - * \param pressure filled with pressure value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down a pointer filled with true if the finger is down, false + * otherwise, may be NULL. + * \param x a pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param y a pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be NULL. + * \param pressure a pointer filled with pressure value, may be NULL. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumGamepadTouchpadFingers */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamepad, int touchpad, int finger, bool *down, float *x, float *y, float *pressure); /** * Return whether a gamepad has a particular sensor. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. + * \returns true if the sensor exists, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadSensorData * \sa SDL_GetGamepadSensorDataRate * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Set whether data reporting for a gamepad sensor is enabled. @@ -1287,28 +1326,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, * \param gamepad the gamepad to update. * \param type the type of sensor to enable/disable. * \param enabled whether data reporting should be enabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GamepadHasSensor * \sa SDL_GamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type, bool enabled); /** * Query whether sensor data reporting is enabled for a gamepad. * * \param gamepad the gamepad to query. * \param type the type of sensor to query. - * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. + * \returns true if the sensor is enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetGamepadSensorEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); +extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); /** * Get the data rate (number of events per second) of a gamepad sensor. @@ -1317,7 +1356,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamep * \param type the type of sensor to query. * \returns the data rate, or 0.0f if the data rate is not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); @@ -1331,12 +1370,12 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game * \param type the type of sensor to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); /** * Start a rumble effect on a gamepad. @@ -1353,12 +1392,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamep * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the gamepad's triggers. @@ -1379,14 +1418,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uin * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleGamepad */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a gamepad's LED color. @@ -1401,12 +1440,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *game * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** * Send a gamepad specific effect packet. @@ -1414,12 +1453,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uin * \param gamepad the gamepad to affect. * \param data the data to send to the gamepad. * \param size the size of the data to send to the gamepad. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); /** * Close a gamepad previously opened with SDL_OpenGamepad(). @@ -1427,7 +1466,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenGamepad */ @@ -1441,7 +1480,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); * \param button a button on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis */ @@ -1454,7 +1493,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt * \param axis an axis on the gamepad. * \returns the sfSymbolsName or NULL if the name can't be found. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGamepadAppleSFSymbolsNameForButton */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h index bba47cc..fa870a5 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_gpu.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,7 +24,281 @@ /** * # CategoryGPU * - * Include file for SDL GPU API functions + * The GPU API offers a cross-platform way for apps to talk to modern graphics + * hardware. It offers both 3D graphics and compute support, in the style of + * Metal, Vulkan, and Direct3D 12. + * + * A basic workflow might be something like this: + * + * The app creates a GPU device with SDL_CreateGPUDevice(), and assigns it to + * a window with SDL_ClaimWindowForGPUDevice()--although strictly speaking you + * can render offscreen entirely, perhaps for image processing, and not use a + * window at all. + * + * Next the app prepares static data (things that are created once and used + * over and over). For example: + * + * - Shaders (programs that run on the GPU): use SDL_CreateGPUShader(). + * - Vertex buffers (arrays of geometry data) and other data rendering will + * need: use SDL_UploadToGPUBuffer(). + * - Textures (images): use SDL_UploadToGPUTexture(). + * - Samplers (how textures should be read from): use SDL_CreateGPUSampler(). + * - Render pipelines (precalculated rendering state): use + * SDL_CreateGPUGraphicsPipeline() + * + * To render, the app creates one or more command buffers, with + * SDL_AcquireGPUCommandBuffer(). Command buffers collect rendering + * instructions that will be submitted to the GPU in batch. Complex scenes can + * use multiple command buffers, maybe configured across multiple threads in + * parallel, as long as they are submitted in the correct order, but many apps + * will just need one command buffer per frame. + * + * Rendering can happen to a texture (what other APIs call a "render target") + * or it can happen to the swapchain texture (which is just a special texture + * that represents a window's contents). The app can use + * SDL_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. */ #ifndef SDL_gpu_h_ @@ -44,132 +318,394 @@ extern "C" { /* Type Declarations */ +/** + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + */ typedef struct SDL_GPUDevice SDL_GPUDevice; + +/** + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + */ typedef struct SDL_GPUBuffer SDL_GPUBuffer; + +/** + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + */ typedef struct SDL_GPUTransferBuffer SDL_GPUTransferBuffer; + +/** + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + */ typedef struct SDL_GPUTexture SDL_GPUTexture; + +/** + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + */ typedef struct SDL_GPUSampler SDL_GPUSampler; + +/** + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + */ typedef struct SDL_GPUShader SDL_GPUShader; + +/** + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + */ typedef struct SDL_GPUComputePipeline SDL_GPUComputePipeline; + +/** + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + */ typedef struct SDL_GPUGraphicsPipeline SDL_GPUGraphicsPipeline; + +/** + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ typedef struct SDL_GPUCommandBuffer SDL_GPUCommandBuffer; + +/** + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + */ typedef struct SDL_GPURenderPass SDL_GPURenderPass; + +/** + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + */ typedef struct SDL_GPUComputePass SDL_GPUComputePass; + +/** + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + */ typedef struct SDL_GPUCopyPass SDL_GPUCopyPass; + +/** + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + */ typedef struct SDL_GPUFence SDL_GPUFence; +/** + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk::builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUPrimitiveType { - SDL_GPU_PRIMITIVETYPE_POINTLIST, - SDL_GPU_PRIMITIVETYPE_LINELIST, - SDL_GPU_PRIMITIVETYPE_LINESTRIP, - SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, - SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST, /**< A series of separate triangles. */ + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP, /**< A series of connected triangles. */ + SDL_GPU_PRIMITIVETYPE_LINELIST, /**< A series of separate lines. */ + SDL_GPU_PRIMITIVETYPE_LINESTRIP, /**< A series of connected lines. */ + SDL_GPU_PRIMITIVETYPE_POINTLIST /**< A series of separate points. */ } SDL_GPUPrimitiveType; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPULoadOp { - SDL_GPU_LOADOP_LOAD, - SDL_GPU_LOADOP_CLEAR, - SDL_GPU_LOADOP_DONT_CARE + SDL_GPU_LOADOP_LOAD, /**< The previous contents of the texture will be preserved. */ + SDL_GPU_LOADOP_CLEAR, /**< The contents of the texture will be cleared to a color. */ + SDL_GPU_LOADOP_DONT_CARE /**< The previous contents of the texture need not be preserved. The contents will be undefined. */ } SDL_GPULoadOp; +/** + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ typedef enum SDL_GPUStoreOp { - SDL_GPU_STOREOP_STORE, - SDL_GPU_STOREOP_DONT_CARE + SDL_GPU_STOREOP_STORE, /**< The contents generated during the render pass will be written to memory. */ + SDL_GPU_STOREOP_DONT_CARE, /**< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. */ + SDL_GPU_STOREOP_RESOLVE, /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture may then be discarded and will be undefined. */ + SDL_GPU_STOREOP_RESOLVE_AND_STORE /**< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. */ } SDL_GPUStoreOp; +/** + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUIndexElementSize { - SDL_GPU_INDEXELEMENTSIZE_16BIT, - SDL_GPU_INDEXELEMENTSIZE_32BIT + SDL_GPU_INDEXELEMENTSIZE_16BIT, /**< The index elements are 16-bit. */ + SDL_GPU_INDEXELEMENTSIZE_32BIT /**< The index elements are 32-bit. */ } SDL_GPUIndexElementSize; -/* Texture format support varies depending on driver, hardware, and usage flags. - * In general, you should use SDL_GPUTextureSupportsFormat to query if a format - * is supported before using it. However, there are a few guaranteed formats. +/** + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE * * For SAMPLER usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R8G8_SNORM - * - R8G8B8A8_SNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB - * - D16_UNORM + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM * * For COLOR_TARGET usage, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - B8G8R8A8_UNORM - * - R8_UNORM - * - R16_FLOAT - * - R16G16_FLOAT - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT - * - R8G8B8A8_UNORM_SRGB - * - B8G8R8A8_UNORM_SRGB + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB * * For STORAGE usages, the following formats are universally supported: - * - R8G8B8A8_UNORM - * - R8G8B8A8_SNORM - * - R16G16B16A16_FLOAT - * - R32_FLOAT - * - R32G32_FLOAT - * - R32G32B32A32_FLOAT - * - R8_UINT - * - R8G8_UINT - * - R8G8B8A8_UINT - * - R16_UINT - * - R16G16_UINT - * - R16G16B16A16_UINT * - * For DEPTH_STENCIL_TARGET usage, the following formats are universally supported: - * - D16_UNORM - * - Either (but not necessarily both!) D24_UNORM or D32_SFLOAT - * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_SFLOAT_S8_UINT + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT * - * Unless D16_UNORM is sufficient for your purposes, always check which - * of D24/D32 is supported before creating a depth-stencil texture! + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat */ typedef enum SDL_GPUTextureFormat { - SDL_GPU_TEXTUREFORMAT_INVALID = -1, + SDL_GPU_TEXTUREFORMAT_INVALID, /* Unsigned Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8_UNORM, + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, - SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, + SDL_GPU_TEXTUREFORMAT_R16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM, SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM, SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM, - SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16_UNORM, - SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM, - SDL_GPU_TEXTUREFORMAT_R8_UNORM, - SDL_GPU_TEXTUREFORMAT_A8_UNORM, + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM, /* Compressed Unsigned Normalized Float Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC1_UNORM, - SDL_GPU_TEXTUREFORMAT_BC2_UNORM, - SDL_GPU_TEXTUREFORMAT_BC3_UNORM, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM, + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM, + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM, + /* Compressed Signed Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT, + /* Compressed Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT, /* Signed Normalized Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8_SNORM, SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM, + SDL_GPU_TEXTUREFORMAT_R16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM, /* Signed Float Color Formats */ SDL_GPU_TEXTUREFORMAT_R16_FLOAT, SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT, @@ -177,6 +713,8 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT, SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT, + /* Unsigned Float Color Formats */ + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT, /* Unsigned Integer Color Formats */ SDL_GPU_TEXTUREFORMAT_R8_UINT, SDL_GPU_TEXTUREFORMAT_R8G8_UINT, @@ -184,48 +722,153 @@ typedef enum SDL_GPUTextureFormat SDL_GPU_TEXTUREFORMAT_R16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16_UINT, SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT, + SDL_GPU_TEXTUREFORMAT_R32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32_UINT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT, + /* Signed Integer Color Formats */ + SDL_GPU_TEXTUREFORMAT_R8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8_INT, + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT, + SDL_GPU_TEXTUREFORMAT_R16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16_INT, + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT, + SDL_GPU_TEXTUREFORMAT_R32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32_INT, + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT, /* SRGB Unsigned Normalized Color Formats */ SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB, SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB, /* Compressed SRGB Unsigned Normalized Color Formats */ - SDL_GPU_TEXTUREFORMAT_BC3_UNORM_SRGB, - SDL_GPU_TEXTUREFORMAT_BC7_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB, /* Depth Formats */ SDL_GPU_TEXTUREFORMAT_D16_UNORM, SDL_GPU_TEXTUREFORMAT_D24_UNORM, SDL_GPU_TEXTUREFORMAT_D32_FLOAT, SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT, - SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT, + /* Compressed ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM, + /* Compressed SRGB ASTC Normalized Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB, + /* Compressed ASTC Signed Float Color Formats*/ + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT, + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT } SDL_GPUTextureFormat; -typedef enum SDL_GPUTextureUsageFlagBits -{ - SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT = 0x00000001, - SDL_GPU_TEXTUREUSAGE_COLOR_TARGET_BIT = 0x00000002, - SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET_BIT = 0x00000004, - SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUTextureUsageFlagBits; - +/** + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef Uint32 SDL_GPUTextureUsageFlags; +#define SDL_GPU_TEXTUREUSAGE_SAMPLER (1u << 0) /**< Texture supports sampling. */ +#define SDL_GPU_TEXTUREUSAGE_COLOR_TARGET (1u << 1) /**< Texture is a color render target. */ +#define SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET (1u << 2) /**< Texture is a depth stencil target. */ +#define SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Texture supports storage reads in graphics stages. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Texture supports storage reads in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Texture supports storage writes in the compute stage. */ +#define SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE (1u << 6) /**< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. */ + +/** + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + */ typedef enum SDL_GPUTextureType { - SDL_GPU_TEXTURETYPE_2D, - SDL_GPU_TEXTURETYPE_2D_ARRAY, - SDL_GPU_TEXTURETYPE_3D, - SDL_GPU_TEXTURETYPE_CUBE + SDL_GPU_TEXTURETYPE_2D, /**< The texture is a 2-dimensional image. */ + SDL_GPU_TEXTURETYPE_2D_ARRAY, /**< The texture is a 2-dimensional array image. */ + SDL_GPU_TEXTURETYPE_3D, /**< The texture is a 3-dimensional image. */ + SDL_GPU_TEXTURETYPE_CUBE, /**< The texture is a cube image. */ + SDL_GPU_TEXTURETYPE_CUBE_ARRAY /**< The texture is a cube array image. */ } SDL_GPUTextureType; +/** + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + */ typedef enum SDL_GPUSampleCount { - SDL_GPU_SAMPLECOUNT_1, - SDL_GPU_SAMPLECOUNT_2, - SDL_GPU_SAMPLECOUNT_4, - SDL_GPU_SAMPLECOUNT_8 + SDL_GPU_SAMPLECOUNT_1, /**< No multisampling. */ + SDL_GPU_SAMPLECOUNT_2, /**< MSAA 2x */ + SDL_GPU_SAMPLECOUNT_4, /**< MSAA 4x */ + SDL_GPU_SAMPLECOUNT_8 /**< MSAA 8x */ } SDL_GPUSampleCount; + +/** + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_GPUCubeMapFace { SDL_GPU_CUBEMAPFACE_POSITIVEX, @@ -236,45 +879,87 @@ typedef enum SDL_GPUCubeMapFace SDL_GPU_CUBEMAPFACE_NEGATIVEZ } SDL_GPUCubeMapFace; -typedef enum SDL_GPUBufferUsageFlagBits -{ - SDL_GPU_BUFFERUSAGE_VERTEX_BIT = 0x00000001, - SDL_GPU_BUFFERUSAGE_INDEX_BIT = 0x00000002, - SDL_GPU_BUFFERUSAGE_INDIRECT_BIT = 0x00000004, - SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT = 0x00000008, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT = 0x00000020, - SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE_BIT = 0x00000040 -} SDL_GPUBufferUsageFlagBits; - +/** + * Specifies how a buffer is intended to be used by the client. + * + * A buffer must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * Unlike textures, READ | WRITE can be used for simultaneous read-write + * usage. The same data synchronization concerns as textures apply. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + */ typedef Uint32 SDL_GPUBufferUsageFlags; +#define SDL_GPU_BUFFERUSAGE_VERTEX (1u << 0) /**< Buffer is a vertex buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDEX (1u << 1) /**< Buffer is an index buffer. */ +#define SDL_GPU_BUFFERUSAGE_INDIRECT (1u << 2) /**< Buffer is an indirect buffer. */ +#define SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ (1u << 3) /**< Buffer supports storage reads in graphics stages. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ (1u << 4) /**< Buffer supports storage reads in the compute stage. */ +#define SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE (1u << 5) /**< Buffer supports storage writes in the compute stage. */ + +/** + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef enum SDL_GPUTransferBufferUsage { SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD, SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD } SDL_GPUTransferBufferUsage; +/** + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef enum SDL_GPUShaderStage { SDL_GPU_SHADERSTAGE_VERTEX, SDL_GPU_SHADERSTAGE_FRAGMENT } SDL_GPUShaderStage; -typedef enum SDL_GPUShaderFormatFlagBits -{ - SDL_GPU_SHADERFORMAT_INVALID = 0x00000000, - SDL_GPU_SHADERFORMAT_SECRET = 0x00000001, /* NDA'd platforms */ - SDL_GPU_SHADERFORMAT_SPIRV = 0x00000002, /* Vulkan */ - SDL_GPU_SHADERFORMAT_DXBC = 0x00000004, /* D3D11 (Shader Model 5_0) */ - SDL_GPU_SHADERFORMAT_DXIL = 0x00000008, /* D3D12 */ - SDL_GPU_SHADERFORMAT_MSL = 0x00000010, /* Metal */ - SDL_GPU_SHADERFORMAT_METALLIB = 0x00000020, /* Metal */ -} SDL_GPUShaderFormatFlagBits; - +/** + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef Uint32 SDL_GPUShaderFormat; +#define SDL_GPU_SHADERFORMAT_INVALID 0 +#define SDL_GPU_SHADERFORMAT_PRIVATE (1u << 0) /**< Shaders for NDA'd platforms. */ +#define SDL_GPU_SHADERFORMAT_SPIRV (1u << 1) /**< SPIR-V shaders for Vulkan. */ +#define SDL_GPU_SHADERFORMAT_DXBC (1u << 2) /**< DXBC SM5_1 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_DXIL (1u << 3) /**< DXIL SM6_0 shaders for D3D12. */ +#define SDL_GPU_SHADERFORMAT_MSL (1u << 4) /**< MSL shaders for Metal. */ +#define SDL_GPU_SHADERFORMAT_METALLIB (1u << 5) /**< Precompiled metallib shaders for Metal. */ + +/** + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexElementFormat { + SDL_GPU_VERTEXELEMENTFORMAT_INVALID, + /* 32-bit Signed Integers */ SDL_GPU_VERTEXELEMENTFORMAT_INT, SDL_GPU_VERTEXELEMENTFORMAT_INT2, @@ -330,125 +1015,230 @@ typedef enum SDL_GPUVertexElementFormat SDL_GPU_VERTEXELEMENTFORMAT_HALF4 } SDL_GPUVertexElementFormat; +/** + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUVertexInputRate { - SDL_GPU_VERTEXINPUTRATE_VERTEX = 0, - SDL_GPU_VERTEXINPUTRATE_INSTANCE = 1 + SDL_GPU_VERTEXINPUTRATE_VERTEX, /**< Attribute addressing is a function of the vertex index. */ + SDL_GPU_VERTEXINPUTRATE_INSTANCE /**< Attribute addressing is a function of the instance index. */ } SDL_GPUVertexInputRate; +/** + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFillMode { - SDL_GPU_FILLMODE_FILL, - SDL_GPU_FILLMODE_LINE + SDL_GPU_FILLMODE_FILL, /**< Polygons will be rendered via rasterization. */ + SDL_GPU_FILLMODE_LINE /**< Polygon edges will be drawn as line segments. */ } SDL_GPUFillMode; +/** + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCullMode { - SDL_GPU_CULLMODE_NONE, - SDL_GPU_CULLMODE_FRONT, - SDL_GPU_CULLMODE_BACK + SDL_GPU_CULLMODE_NONE, /**< No triangles are culled. */ + SDL_GPU_CULLMODE_FRONT, /**< Front-facing triangles are culled. */ + SDL_GPU_CULLMODE_BACK /**< Back-facing triangles are culled. */ } SDL_GPUCullMode; +/** + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUFrontFace { - SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, - SDL_GPU_FRONTFACE_CLOCKWISE + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE, /**< A triangle with counter-clockwise vertex winding will be considered front-facing. */ + SDL_GPU_FRONTFACE_CLOCKWISE /**< A triangle with clockwise vertex winding will be considered front-facing. */ } SDL_GPUFrontFace; +/** + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUCompareOp { - SDL_GPU_COMPAREOP_NEVER, - SDL_GPU_COMPAREOP_LESS, - SDL_GPU_COMPAREOP_EQUAL, - SDL_GPU_COMPAREOP_LESS_OR_EQUAL, - SDL_GPU_COMPAREOP_GREATER, - SDL_GPU_COMPAREOP_NOT_EQUAL, - SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, - SDL_GPU_COMPAREOP_ALWAYS + SDL_GPU_COMPAREOP_INVALID, + SDL_GPU_COMPAREOP_NEVER, /**< The comparison always evaluates false. */ + SDL_GPU_COMPAREOP_LESS, /**< The comparison evaluates reference < test. */ + SDL_GPU_COMPAREOP_EQUAL, /**< The comparison evaluates reference == test. */ + SDL_GPU_COMPAREOP_LESS_OR_EQUAL, /**< The comparison evaluates reference <= test. */ + SDL_GPU_COMPAREOP_GREATER, /**< The comparison evaluates reference > test. */ + SDL_GPU_COMPAREOP_NOT_EQUAL, /**< The comparison evaluates reference != test. */ + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL, /**< The comparison evalutes reference >= test. */ + SDL_GPU_COMPAREOP_ALWAYS /**< The comparison always evaluates true. */ } SDL_GPUCompareOp; +/** + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUStencilOp { - SDL_GPU_STENCILOP_KEEP, - SDL_GPU_STENCILOP_ZERO, - SDL_GPU_STENCILOP_REPLACE, - SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, - SDL_GPU_STENCILOP_INVERT, - SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, - SDL_GPU_STENCILOP_DECREMENT_AND_WRAP + SDL_GPU_STENCILOP_INVALID, + SDL_GPU_STENCILOP_KEEP, /**< Keeps the current value. */ + SDL_GPU_STENCILOP_ZERO, /**< Sets the value to 0. */ + SDL_GPU_STENCILOP_REPLACE, /**< Sets the value to reference. */ + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP, /**< Increments the current value and clamps to the maximum value. */ + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP, /**< Decrements the current value and clamps to 0. */ + SDL_GPU_STENCILOP_INVERT, /**< Bitwise-inverts the current value. */ + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP, /**< Increments the current value and wraps back to 0. */ + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP /**< Decrements the current value and wraps to the maximum value. */ } SDL_GPUStencilOp; +/** + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendOp { - SDL_GPU_BLENDOP_ADD, - SDL_GPU_BLENDOP_SUBTRACT, - SDL_GPU_BLENDOP_REVERSE_SUBTRACT, - SDL_GPU_BLENDOP_MIN, - SDL_GPU_BLENDOP_MAX + SDL_GPU_BLENDOP_INVALID, + SDL_GPU_BLENDOP_ADD, /**< (source * source_factor) + (destination * destination_factor) */ + SDL_GPU_BLENDOP_SUBTRACT, /**< (source * source_factor) - (destination * destination_factor) */ + SDL_GPU_BLENDOP_REVERSE_SUBTRACT, /**< (destination * destination_factor) - (source * source_factor) */ + SDL_GPU_BLENDOP_MIN, /**< min(source, destination) */ + SDL_GPU_BLENDOP_MAX /**< max(source, destination) */ } SDL_GPUBlendOp; +/** + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef enum SDL_GPUBlendFactor { - SDL_GPU_BLENDFACTOR_ZERO, - SDL_GPU_BLENDFACTOR_ONE, - SDL_GPU_BLENDFACTOR_SRC_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, - SDL_GPU_BLENDFACTOR_DST_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, - SDL_GPU_BLENDFACTOR_DST_ALPHA, - SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, - SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, - SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE + SDL_GPU_BLENDFACTOR_INVALID, + SDL_GPU_BLENDFACTOR_ZERO, /**< 0 */ + SDL_GPU_BLENDFACTOR_ONE, /**< 1 */ + SDL_GPU_BLENDFACTOR_SRC_COLOR, /**< source color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR, /**< 1 - source color */ + SDL_GPU_BLENDFACTOR_DST_COLOR, /**< destination color */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR, /**< 1 - destination color */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA, /**< source alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA, /**< 1 - source alpha */ + SDL_GPU_BLENDFACTOR_DST_ALPHA, /**< destination alpha */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA, /**< 1 - destination alpha */ + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR, /**< blend constant */ + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR, /**< 1 - blend constant */ + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE /**< min(source alpha, 1 - destination alpha) */ } SDL_GPUBlendFactor; -typedef enum SDL_GPUColorComponentFlagBits -{ - SDL_GPU_COLORCOMPONENT_R_BIT = 0x00000001, - SDL_GPU_COLORCOMPONENT_G_BIT = 0x00000002, - SDL_GPU_COLORCOMPONENT_B_BIT = 0x00000004, - SDL_GPU_COLORCOMPONENT_A_BIT = 0x00000008 -} SDL_GPUColorComponentFlagBits; - +/** + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + */ typedef Uint8 SDL_GPUColorComponentFlags; +#define SDL_GPU_COLORCOMPONENT_R (1u << 0) /**< the red component */ +#define SDL_GPU_COLORCOMPONENT_G (1u << 1) /**< the green component */ +#define SDL_GPU_COLORCOMPONENT_B (1u << 2) /**< the blue component */ +#define SDL_GPU_COLORCOMPONENT_A (1u << 3) /**< the alpha component */ + +/** + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUFilter { - SDL_GPU_FILTER_NEAREST, - SDL_GPU_FILTER_LINEAR + SDL_GPU_FILTER_NEAREST, /**< Point filtering. */ + SDL_GPU_FILTER_LINEAR /**< Linear filtering. */ } SDL_GPUFilter; +/** + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerMipmapMode { - SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, - SDL_GPU_SAMPLERMIPMAPMODE_LINEAR + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST, /**< Point filtering. */ + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR /**< Linear filtering. */ } SDL_GPUSamplerMipmapMode; +/** + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef enum SDL_GPUSamplerAddressMode { - SDL_GPU_SAMPLERADDRESSMODE_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, - SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE + SDL_GPU_SAMPLERADDRESSMODE_REPEAT, /**< Specifies that the coordinates will wrap around. */ + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT, /**< Specifies that the coordinates will wrap around mirrored. */ + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE /**< Specifies that the coordinates will clamp to the 0-1 range. */ } SDL_GPUSamplerAddressMode; -/* - * VSYNC: - * Waits for vblank before presenting. - * If there is a pending image to present, the new image is enqueued for presentation. - * Disallows tearing at the cost of visual latency. - * When using this present mode, AcquireSwapchainTexture will block if too many frames are in flight. - * IMMEDIATE: - * Immediately presents. - * Lowest latency option, but tearing may occur. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. - * MAILBOX: - * Waits for vblank before presenting. No tearing is possible. - * If there is a pending image to present, the pending image is replaced by the new image. - * Similar to VSYNC, but with reduced visual latency. - * When using this mode, AcquireSwapchainTexture will return NULL if too many frames are in flight. +/** + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUPresentMode { @@ -457,493 +1247,866 @@ typedef enum SDL_GPUPresentMode SDL_GPU_PRESENTMODE_MAILBOX } SDL_GPUPresentMode; -/* - * SDR: - * B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in nonlinear sRGB encoding. Blends raw pixel values. - * SDR_LINEAR: - * B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are in nonlinear sRGB encoding. Blends in linear space. - * HDR_EXTENDED_LINEAR: - * R16G16B16A16_SFLOAT swapchain. Pixel values are in extended linear encoding. Blends in linear space. - * HDR10_ST2048: - * A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in PQ ST2048 encoding. Blends raw pixel values. (TODO: verify this) +/** + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture */ typedef enum SDL_GPUSwapchainComposition { SDL_GPU_SWAPCHAINCOMPOSITION_SDR, SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR, SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR, - SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2048 + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 } SDL_GPUSwapchainComposition; -typedef enum SDL_GPUDriver -{ - SDL_GPU_DRIVER_INVALID = -1, - SDL_GPU_DRIVER_SECRET, /* NDA'd platforms */ - SDL_GPU_DRIVER_VULKAN, - SDL_GPU_DRIVER_D3D11, - SDL_GPU_DRIVER_D3D12, - SDL_GPU_DRIVER_METAL -} SDL_GPUDriver; - /* Structures */ -typedef struct SDL_GPUDepthStencilValue -{ - float depth; - Uint8 stencil; -} SDL_GPUDepthStencilValue; - +/** + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + */ typedef struct SDL_GPUViewport { - float x; - float y; - float w; - float h; - float minDepth; - float maxDepth; + float x; /**< The left offset of the viewport. */ + float y; /**< The top offset of the viewport. */ + float w; /**< The width of the viewport. */ + float h; /**< The height of the viewport. */ + float min_depth; /**< The minimum depth of the viewport. */ + float max_depth; /**< The maximum depth of the viewport. */ } SDL_GPUViewport; +/** + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureTransferInfo { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; /* starting location of the image data */ - Uint32 imagePitch; /* number of pixels from one row to the next */ - Uint32 imageHeight; /* number of rows from one layer/depth-slice to the next */ + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the image data in the transfer buffer. */ + Uint32 pixels_per_row; /**< The number of pixels from one row to the next. */ + Uint32 rows_per_layer; /**< The number of rows from one layer/depth-slice to the next. */ } SDL_GPUTextureTransferInfo; +/** + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUTransferBufferLocation { - SDL_GPUTransferBuffer *transferBuffer; - Uint32 offset; + SDL_GPUTransferBuffer *transfer_buffer; /**< The transfer buffer used in the transfer operation. */ + Uint32 offset; /**< The starting byte of the buffer data in the transfer buffer. */ } SDL_GPUTransferBufferLocation; +/** + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + */ typedef struct SDL_GPUTextureLocation { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index of the location. */ + Uint32 layer; /**< The layer index of the location. */ + Uint32 x; /**< The left offset of the location. */ + Uint32 y; /**< The top offset of the location. */ + Uint32 z; /**< The front offset of the location. */ } SDL_GPUTextureLocation; +/** + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + */ typedef struct SDL_GPUTextureRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - Uint32 x; - Uint32 y; - Uint32 z; - Uint32 w; - Uint32 h; - Uint32 d; + SDL_GPUTexture *texture; /**< The texture used in the copy operation. */ + Uint32 mip_level; /**< The mip level index to transfer. */ + Uint32 layer; /**< The layer index to transfer. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 z; /**< The front offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ + Uint32 d; /**< The depth of the region. */ } SDL_GPUTextureRegion; +/** + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ typedef struct SDL_GPUBlitRegion { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; - Uint32 x; - Uint32 y; - Uint32 w; - Uint32 h; + SDL_GPUTexture *texture; /**< The texture. */ + Uint32 mip_level; /**< The mip level index of the region. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane of the region. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + Uint32 x; /**< The left offset of the region. */ + Uint32 y; /**< The top offset of the region. */ + Uint32 w; /**< The width of the region. */ + Uint32 h; /**< The height of the region. */ } SDL_GPUBlitRegion; +/** + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + */ typedef struct SDL_GPUBufferLocation { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ } SDL_GPUBufferLocation; +/** + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + */ typedef struct SDL_GPUBufferRegion { - SDL_GPUBuffer *buffer; - Uint32 offset; - Uint32 size; + SDL_GPUBuffer *buffer; /**< The buffer. */ + Uint32 offset; /**< The starting byte within the buffer. */ + Uint32 size; /**< The size in bytes of the region. */ } SDL_GPUBufferRegion; -/* Note that the `firstVertex` and `firstInstance` parameters are NOT compatible with - * built-in vertex/instance ID variables in shaders (for example, SV_VertexID). If - * your shader depends on these variables, the correlating draw call parameter MUST - * be 0. +/** + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect */ typedef struct SDL_GPUIndirectDrawCommand { - Uint32 vertexCount; /* number of vertices to draw */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstVertex; /* index of the first vertex to draw */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_vertices; /**< The number of vertices to draw. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_vertex; /**< The index of the first vertex to draw. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + */ typedef struct SDL_GPUIndexedIndirectDrawCommand { - Uint32 indexCount; /* number of vertices to draw per instance */ - Uint32 instanceCount; /* number of instances to draw */ - Uint32 firstIndex; /* base index within the index buffer */ - Sint32 vertexOffset; /* value added to vertex index before indexing into the vertex buffer */ - Uint32 firstInstance; /* ID of the first instance to draw */ + Uint32 num_indices; /**< The number of indices to draw per instance. */ + Uint32 num_instances; /**< The number of instances to draw. */ + Uint32 first_index; /**< The base index within the index buffer. */ + Sint32 vertex_offset; /**< The value added to the vertex index before indexing into the vertex buffer. */ + Uint32 first_instance; /**< The ID of the first instance to draw. */ } SDL_GPUIndexedIndirectDrawCommand; +/** + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + */ typedef struct SDL_GPUIndirectDispatchCommand { - Uint32 groupCountX; - Uint32 groupCountY; - Uint32 groupCountZ; + Uint32 groupcount_x; /**< The number of local workgroups to dispatch in the X dimension. */ + Uint32 groupcount_y; /**< The number of local workgroups to dispatch in the Y dimension. */ + Uint32 groupcount_z; /**< The number of local workgroups to dispatch in the Z dimension. */ } SDL_GPUIndirectDispatchCommand; /* State structures */ +/** + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + */ typedef struct SDL_GPUSamplerCreateInfo { - SDL_GPUFilter minFilter; - SDL_GPUFilter magFilter; - SDL_GPUSamplerMipmapMode mipmapMode; - SDL_GPUSamplerAddressMode addressModeU; - SDL_GPUSamplerAddressMode addressModeV; - SDL_GPUSamplerAddressMode addressModeW; - float mipLodBias; - SDL_bool anisotropyEnable; - float maxAnisotropy; - SDL_bool compareEnable; - SDL_GPUCompareOp compareOp; - float minLod; - float maxLod; + SDL_GPUFilter min_filter; /**< The minification filter to apply to lookups. */ + SDL_GPUFilter mag_filter; /**< The magnification filter to apply to lookups. */ + SDL_GPUSamplerMipmapMode mipmap_mode; /**< The mipmap filter to apply to lookups. */ + SDL_GPUSamplerAddressMode address_mode_u; /**< The addressing mode for U coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_v; /**< The addressing mode for V coordinates outside [0, 1). */ + SDL_GPUSamplerAddressMode address_mode_w; /**< The addressing mode for W coordinates outside [0, 1). */ + float mip_lod_bias; /**< The bias to be added to mipmap LOD calculation. */ + float max_anisotropy; /**< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator to apply to fetched data before filtering. */ + float min_lod; /**< Clamps the minimum of the computed LOD value. */ + float max_lod; /**< Clamps the maximum of the computed LOD value. */ + bool enable_anisotropy; /**< true to enable anisotropic filtering. */ + bool enable_compare; /**< true to enable comparison against a reference value during lookups. */ + Uint8 padding1; + Uint8 padding2; - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUSamplerCreateInfo; -typedef struct SDL_GPUVertexBinding +/** + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + */ +typedef struct SDL_GPUVertexBufferDescription { - Uint32 binding; - Uint32 stride; - SDL_GPUVertexInputRate inputRate; - Uint32 instanceStepRate; /* ignored unless inputRate is INSTANCE */ -} SDL_GPUVertexBinding; + Uint32 slot; /**< The binding slot of the vertex buffer. */ + Uint32 pitch; /**< The byte pitch between consecutive elements of the vertex buffer. */ + SDL_GPUVertexInputRate input_rate; /**< Whether attribute addressing is a function of the vertex index or instance index. */ + Uint32 instance_step_rate; /**< The number of instances to draw using the same per-instance data before advancing in the instance buffer by one element. Ignored unless input_rate is SDL_GPU_VERTEXINPUTRATE_INSTANCE */ +} SDL_GPUVertexBufferDescription; +/** + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + */ typedef struct SDL_GPUVertexAttribute { - Uint32 location; - Uint32 binding; - SDL_GPUVertexElementFormat format; - Uint32 offset; + Uint32 location; /**< The shader input location index. */ + Uint32 buffer_slot; /**< The binding slot of the associated vertex buffer. */ + SDL_GPUVertexElementFormat format; /**< The size and type of the attribute data. */ + Uint32 offset; /**< The byte offset of this attribute relative to the start of the vertex element. */ } SDL_GPUVertexAttribute; +/** + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + */ typedef struct SDL_GPUVertexInputState { - const SDL_GPUVertexBinding *vertexBindings; - Uint32 vertexBindingCount; - const SDL_GPUVertexAttribute *vertexAttributes; - Uint32 vertexAttributeCount; + const SDL_GPUVertexBufferDescription *vertex_buffer_descriptions; /**< A pointer to an array of vertex buffer descriptions. */ + Uint32 num_vertex_buffers; /**< The number of vertex buffer descriptions in the above array. */ + const SDL_GPUVertexAttribute *vertex_attributes; /**< A pointer to an array of vertex attribute descriptions. */ + Uint32 num_vertex_attributes; /**< The number of vertex attribute descriptions in the above array. */ } SDL_GPUVertexInputState; +/** + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + */ typedef struct SDL_GPUStencilOpState { - SDL_GPUStencilOp failOp; - SDL_GPUStencilOp passOp; - SDL_GPUStencilOp depthFailOp; - SDL_GPUCompareOp compareOp; + SDL_GPUStencilOp fail_op; /**< The action performed on samples that fail the stencil test. */ + SDL_GPUStencilOp pass_op; /**< The action performed on samples that pass the depth and stencil tests. */ + SDL_GPUStencilOp depth_fail_op; /**< The action performed on samples that pass the stencil test and fail the depth test. */ + SDL_GPUCompareOp compare_op; /**< The comparison operator used in the stencil test. */ } SDL_GPUStencilOpState; -typedef struct SDL_GPUColorAttachmentBlendState +/** + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + */ +typedef struct SDL_GPUColorTargetBlendState { - SDL_bool blendEnable; - SDL_GPUBlendFactor srcColorBlendFactor; - SDL_GPUBlendFactor dstColorBlendFactor; - SDL_GPUBlendOp colorBlendOp; - SDL_GPUBlendFactor srcAlphaBlendFactor; - SDL_GPUBlendFactor dstAlphaBlendFactor; - SDL_GPUBlendOp alphaBlendOp; - SDL_GPUColorComponentFlags colorWriteMask; -} SDL_GPUColorAttachmentBlendState; + SDL_GPUBlendFactor src_color_blendfactor; /**< The value to be multiplied by the source RGB value. */ + SDL_GPUBlendFactor dst_color_blendfactor; /**< The value to be multiplied by the destination RGB value. */ + SDL_GPUBlendOp color_blend_op; /**< The blend operation for the RGB components. */ + SDL_GPUBlendFactor src_alpha_blendfactor; /**< The value to be multiplied by the source alpha. */ + SDL_GPUBlendFactor dst_alpha_blendfactor; /**< The value to be multiplied by the destination alpha. */ + SDL_GPUBlendOp alpha_blend_op; /**< The blend operation for the alpha component. */ + SDL_GPUColorComponentFlags color_write_mask; /**< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. */ + bool enable_blend; /**< Whether blending is enabled for the color target. */ + bool enable_color_write_mask; /**< Whether the color write mask is enabled. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetBlendState; + +/** + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + */ typedef struct SDL_GPUShaderCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - SDL_GPUShaderStage stage; - Uint32 samplerCount; - Uint32 storageTextureCount; - Uint32 storageBufferCount; - Uint32 uniformBufferCount; + size_t code_size; /**< The size in bytes of the code pointed to. */ + const Uint8 *code; /**< A pointer to shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the shader code. */ + SDL_GPUShaderStage stage; /**< The stage the shader program corresponds to. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_storage_textures; /**< The number of storage textures defined in the shader. */ + Uint32 num_storage_buffers; /**< The number of storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUShaderCreateInfo; +/** + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + */ typedef struct SDL_GPUTextureCreateInfo { - SDL_GPUTextureType type; - SDL_GPUTextureFormat format; - SDL_GPUTextureUsageFlags usageFlags; - Uint32 width; - Uint32 height; - Uint32 layerCountOrDepth; - Uint32 levelCount; - SDL_GPUSampleCount sampleCount; + SDL_GPUTextureType type; /**< The base dimensionality of the texture. */ + SDL_GPUTextureFormat format; /**< The pixel format of the texture. */ + SDL_GPUTextureUsageFlags usage; /**< How the texture is intended to be used by the client. */ + Uint32 width; /**< The width of the texture. */ + Uint32 height; /**< The height of the texture. */ + Uint32 layer_count_or_depth; /**< The layer count or depth of the texture. This value is treated as a layer count on 2D array textures, and as a depth value on 3D textures. */ + Uint32 num_levels; /**< The number of mip levels in the texture. */ + SDL_GPUSampleCount sample_count; /**< The number of samples per texel. Only applies if the texture is used as a render target. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTextureCreateInfo; -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" - +/** + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + */ typedef struct SDL_GPUBufferCreateInfo { - SDL_GPUBufferUsageFlags usageFlags; - Uint32 sizeInBytes; + SDL_GPUBufferUsageFlags usage; /**< How the buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUBufferCreateInfo; +/** + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + */ typedef struct SDL_GPUTransferBufferCreateInfo { - SDL_GPUTransferBufferUsage usage; - Uint32 sizeInBytes; + SDL_GPUTransferBufferUsage usage; /**< How the transfer buffer is intended to be used by the client. */ + Uint32 size; /**< The size in bytes of the transfer buffer. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTransferBufferCreateInfo; /* Pipeline state structures */ +/** + * A structure specifying the parameters of the graphics pipeline rasterizer + * state. + * + * NOTE: Some backend APIs (D3D11/12) will enable depth clamping even if + * enable_depth_clip is true. If you rely on this clamp+clip behavior, + * consider enabling depth clip and then manually clamping depth in your + * fragment shaders on Metal and Vulkan. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPURasterizerState { - SDL_GPUFillMode fillMode; - SDL_GPUCullMode cullMode; - SDL_GPUFrontFace frontFace; - SDL_bool depthBiasEnable; - float depthBiasConstantFactor; - float depthBiasClamp; - float depthBiasSlopeFactor; + SDL_GPUFillMode fill_mode; /**< Whether polygons will be filled in or drawn as lines. */ + SDL_GPUCullMode cull_mode; /**< The facing direction in which triangles will be culled. */ + SDL_GPUFrontFace front_face; /**< The vertex winding that will cause a triangle to be determined as front-facing. */ + float depth_bias_constant_factor; /**< A scalar factor controlling the depth value added to each fragment. */ + float depth_bias_clamp; /**< The maximum depth bias of a fragment. */ + float depth_bias_slope_factor; /**< A scalar factor applied to a fragment's slope in depth calculations. */ + bool enable_depth_bias; /**< true to bias fragment depth values. */ + bool enable_depth_clip; /**< true to enable depth clip, false to enable depth clamp. */ + Uint8 padding1; + Uint8 padding2; } SDL_GPURasterizerState; +/** + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUMultisampleState { - SDL_GPUSampleCount sampleCount; - Uint32 sampleMask; + SDL_GPUSampleCount sample_count; /**< The number of samples to be used in rasterization. */ + Uint32 sample_mask; /**< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. */ + bool enable_mask; /**< Enables sample masking. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUMultisampleState; +/** + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ typedef struct SDL_GPUDepthStencilState { - SDL_bool depthTestEnable; - SDL_bool depthWriteEnable; - SDL_GPUCompareOp compareOp; - SDL_bool stencilTestEnable; - SDL_GPUStencilOpState backStencilState; - SDL_GPUStencilOpState frontStencilState; - Uint8 compareMask; - Uint8 writeMask; - Uint8 reference; + SDL_GPUCompareOp compare_op; /**< The comparison operator used for depth testing. */ + SDL_GPUStencilOpState back_stencil_state; /**< The stencil op state for back-facing triangles. */ + SDL_GPUStencilOpState front_stencil_state; /**< The stencil op state for front-facing triangles. */ + Uint8 compare_mask; /**< Selects the bits of the stencil values participating in the stencil test. */ + Uint8 write_mask; /**< Selects the bits of the stencil values updated by the stencil test. */ + bool enable_depth_test; /**< true enables the depth test. */ + bool enable_depth_write; /**< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. */ + bool enable_stencil_test; /**< true enables the stencil test. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; } SDL_GPUDepthStencilState; -typedef struct SDL_GPUColorAttachmentDescription +/** + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ +typedef struct SDL_GPUColorTargetDescription { - SDL_GPUTextureFormat format; - SDL_GPUColorAttachmentBlendState blendState; -} SDL_GPUColorAttachmentDescription; + SDL_GPUTextureFormat format; /**< The pixel format of the texture to be used as a color target. */ + SDL_GPUColorTargetBlendState blend_state; /**< The blend state to be used for the color target. */ +} SDL_GPUColorTargetDescription; -typedef struct SDL_GPUGraphicsPipelineAttachmentInfo +/** + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + */ +typedef struct SDL_GPUGraphicsPipelineTargetInfo { - SDL_GPUColorAttachmentDescription *colorAttachmentDescriptions; - Uint32 colorAttachmentCount; - SDL_bool hasDepthStencilAttachment; - SDL_GPUTextureFormat depthStencilFormat; -} SDL_GPUGraphicsPipelineAttachmentInfo; + const SDL_GPUColorTargetDescription *color_target_descriptions; /**< A pointer to an array of color target descriptions. */ + Uint32 num_color_targets; /**< The number of color target descriptions in the above array. */ + SDL_GPUTextureFormat depth_stencil_format; /**< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. */ + bool has_depth_stencil_target; /**< true specifies that the pipeline uses a depth-stencil target. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUGraphicsPipelineTargetInfo; +/** + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + */ typedef struct SDL_GPUGraphicsPipelineCreateInfo { - SDL_GPUShader *vertexShader; - SDL_GPUShader *fragmentShader; - SDL_GPUVertexInputState vertexInputState; - SDL_GPUPrimitiveType primitiveType; - SDL_GPURasterizerState rasterizerState; - SDL_GPUMultisampleState multisampleState; - SDL_GPUDepthStencilState depthStencilState; - SDL_GPUGraphicsPipelineAttachmentInfo attachmentInfo; - float blendConstants[4]; + SDL_GPUShader *vertex_shader; /**< The vertex shader used by the graphics pipeline. */ + SDL_GPUShader *fragment_shader; /**< The fragment shader used by the graphics pipeline. */ + SDL_GPUVertexInputState vertex_input_state; /**< The vertex layout of the graphics pipeline. */ + SDL_GPUPrimitiveType primitive_type; /**< The primitive topology of the graphics pipeline. */ + SDL_GPURasterizerState rasterizer_state; /**< The rasterizer state of the graphics pipeline. */ + SDL_GPUMultisampleState multisample_state; /**< The multisample state of the graphics pipeline. */ + SDL_GPUDepthStencilState depth_stencil_state; /**< The depth-stencil state of the graphics pipeline. */ + SDL_GPUGraphicsPipelineTargetInfo target_info; /**< Formats and blend modes for the render targets of the graphics pipeline. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUGraphicsPipelineCreateInfo; +/** + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + */ typedef struct SDL_GPUComputePipelineCreateInfo { - size_t codeSize; - const Uint8 *code; - const char *entryPointName; - SDL_GPUShaderFormat format; - Uint32 readOnlyStorageTextureCount; - Uint32 readOnlyStorageBufferCount; - Uint32 writeOnlyStorageTextureCount; - Uint32 writeOnlyStorageBufferCount; - Uint32 uniformBufferCount; - Uint32 threadCountX; - Uint32 threadCountY; - Uint32 threadCountZ; + size_t code_size; /**< The size in bytes of the compute shader code pointed to. */ + const Uint8 *code; /**< A pointer to compute shader code. */ + const char *entrypoint; /**< A pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. */ + SDL_GPUShaderFormat format; /**< The format of the compute shader code. */ + Uint32 num_samplers; /**< The number of samplers defined in the shader. */ + Uint32 num_readonly_storage_textures; /**< The number of readonly storage textures defined in the shader. */ + Uint32 num_readonly_storage_buffers; /**< The number of readonly storage buffers defined in the shader. */ + Uint32 num_readwrite_storage_textures; /**< The number of read-write storage textures defined in the shader. */ + Uint32 num_readwrite_storage_buffers; /**< The number of read-write storage buffers defined in the shader. */ + Uint32 num_uniform_buffers; /**< The number of uniform buffers defined in the shader. */ + Uint32 threadcount_x; /**< The number of threads in the X dimension. This should match the value in the shader. */ + Uint32 threadcount_y; /**< The number of threads in the Y dimension. This should match the value in the shader. */ + Uint32 threadcount_z; /**< The number of threads in the Z dimension. This should match the value in the shader. */ - SDL_PropertiesID props; + SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUComputePipelineCreateInfo; -typedef struct SDL_GPUColorAttachmentInfo +/** + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUColorTargetInfo { - /* The texture that will be used as a color attachment by a render pass. */ - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layerOrDepthPlane; /* For 3D textures, you can bind an individual depth plane as an attachment. */ + SDL_GPUTexture *texture; /**< The texture that will be used as a color target by a render pass. */ + Uint32 mip_level; /**< The mip level to use as a color target. */ + Uint32 layer_or_depth_plane; /**< The layer index or depth plane to use as a color target. This value is treated as a layer index on 2D array and cube textures, and as a depth plane on 3D textures. */ + SDL_FColor clear_color; /**< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the color target at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the results of the render pass. */ + SDL_GPUTexture *resolve_texture; /**< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_mip_level; /**< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + Uint32 resolve_layer; /**< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. */ + bool cycle; /**< true cycles the texture if the texture is bound and load_op is not LOAD */ + bool cycle_resolve_texture; /**< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUColorTargetInfo; - /* Can be ignored by RenderPass if CLEAR is not used */ - SDL_FColor clearColor; - - /* Determines what is done with the texture at the beginning of the render pass. - * - * LOAD: - * Loads the data currently in the texture. - * - * CLEAR: - * Clears the texture to a single color. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the texture at the end of the render pass. - * - * STORE: - * Stores the results of the render pass in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and loadOp is not LOAD */ - SDL_bool cycle; -} SDL_GPUColorAttachmentInfo; - -typedef struct SDL_GPUDepthStencilAttachmentInfo +/** + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + */ +typedef struct SDL_GPUDepthStencilTargetInfo { - /* The texture that will be used as the depth stencil attachment by a render pass. */ - SDL_GPUTexture *texture; + SDL_GPUTexture *texture; /**< The texture that will be used as the depth stencil target by the render pass. */ + float clear_depth; /**< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + SDL_GPULoadOp load_op; /**< What is done with the depth contents at the beginning of the render pass. */ + SDL_GPUStoreOp store_op; /**< What is done with the depth results of the render pass. */ + SDL_GPULoadOp stencil_load_op; /**< What is done with the stencil contents at the beginning of the render pass. */ + SDL_GPUStoreOp stencil_store_op; /**< What is done with the stencil results of the render pass. */ + bool cycle; /**< true cycles the texture if the texture is bound and any load ops are not LOAD */ + Uint8 clear_stencil; /**< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. */ + Uint8 padding1; + Uint8 padding2; +} SDL_GPUDepthStencilTargetInfo; - /* Can be ignored by the render pass if CLEAR is not used */ - SDL_GPUDepthStencilValue depthStencilClearValue; - - /* Determines what is done with the depth values at the beginning of the render pass. - * - * LOAD: - * Loads the depth values currently in the texture. - * - * CLEAR: - * Clears the texture to a single depth. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp loadOp; - - /* Determines what is done with the depth values at the end of the render pass. - * - * STORE: - * Stores the depth results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp storeOp; - - /* Determines what is done with the stencil values at the beginning of the render pass. - * - * LOAD: - * Loads the stencil values currently in the texture. - * - * CLEAR: - * Clears the texture to a single stencil value. - * - * DONT_CARE: - * The driver will do whatever it wants with the memory. - * This is a good option if you know that every single pixel will be touched in the render pass. - */ - SDL_GPULoadOp stencilLoadOp; - - /* Determines what is done with the stencil values at the end of the render pass. - * - * STORE: - * Stores the stencil results in the texture. - * - * DONT_CARE: - * The driver will do whatever it wants with the texture memory. - * This is often a good option for depth/stencil textures. - */ - SDL_GPUStoreOp stencilStoreOp; - - /* if SDL_TRUE, cycles the texture if the texture is bound and any load ops are not LOAD */ - SDL_bool cycle; -} SDL_GPUDepthStencilAttachmentInfo; +/** + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + */ +typedef struct SDL_GPUBlitInfo { + SDL_GPUBlitRegion source; /**< The source region for the blit. */ + SDL_GPUBlitRegion destination; /**< The destination region for the blit. */ + SDL_GPULoadOp load_op; /**< What is done with the contents of the destination before the blit. */ + SDL_FColor clear_color; /**< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. */ + SDL_FlipMode flip_mode; /**< The flip mode for the source region. */ + SDL_GPUFilter filter; /**< The filter mode used when blitting. */ + bool cycle; /**< true cycles the destination texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUBlitInfo; /* Binding structs */ +/** + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + */ typedef struct SDL_GPUBufferBinding { - SDL_GPUBuffer *buffer; - Uint32 offset; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. */ + Uint32 offset; /**< The starting byte of the data to bind in the buffer. */ } SDL_GPUBufferBinding; +/** + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + */ typedef struct SDL_GPUTextureSamplerBinding { - SDL_GPUTexture *texture; - SDL_GPUSampler *sampler; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. */ + SDL_GPUSampler *sampler; /**< The sampler to bind. */ } SDL_GPUTextureSamplerBinding; -typedef struct SDL_GPUStorageBufferWriteOnlyBinding +/** + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageBufferReadWriteBinding { - SDL_GPUBuffer *buffer; + SDL_GPUBuffer *buffer; /**< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. */ + bool cycle; /**< true cycles the buffer if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageBufferReadWriteBinding; - /* if SDL_TRUE, cycles the buffer if it is bound. */ - SDL_bool cycle; -} SDL_GPUStorageBufferWriteOnlyBinding; - -typedef struct SDL_GPUStorageTextureWriteOnlyBinding +/** + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + */ +typedef struct SDL_GPUStorageTextureReadWriteBinding { - SDL_GPUTexture *texture; - Uint32 mipLevel; - Uint32 layer; - - /* if SDL_TRUE, cycles the texture if the texture is bound. */ - SDL_bool cycle; -} SDL_GPUStorageTextureWriteOnlyBinding; + SDL_GPUTexture *texture; /**< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. */ + Uint32 mip_level; /**< The mip level index to bind. */ + Uint32 layer; /**< The layer index to bind. */ + bool cycle; /**< true cycles the texture if it is already bound. */ + Uint8 padding1; + Uint8 padding2; + Uint8 padding3; +} SDL_GPUStorageTextureReadWriteBinding; /* Functions */ /* Device */ /** - * Creates a GPU context. + * Checks for GPU runtime support. * - * \param formatFlags a bitflag indicating which shader formats the app is - * able to provide. - * \param debugMode enable debug mode properties and validations. + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. * \param name the preferred GPU driver, or NULL to let SDL pick the optimal * driver. - * \returns a GPU context on success or NULL on failure. + * \returns true if supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_CreateGPUDevice + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsShaderFormats( + SDL_GPUShaderFormat format_flags, + const char *name); + +/** + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GPUSupportsProperties( + SDL_PropertiesID props); + +/** + * Creates a GPU context. + * + * \param format_flags a bitflag indicating which shader formats the app is + * able to provide. + * \param debug_mode enable debug mode properties and validations. + * \param name the preferred GPU driver, or NULL to let SDL pick the optimal + * driver. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( - SDL_GPUShaderFormat formatFlags, - SDL_bool debugMode, + SDL_GPUShaderFormat format_flags, + bool debug_mode, const char *name); /** @@ -951,26 +2114,26 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * * These are the supported properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL`: enable debug mode properties - * and validations, defaults to SDL_TRUE. - * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL`: enable to prefer energy - * efficiency over maximum GPU performance, defaults to SDL_FALSE. + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to * use, if a specific one is desired. * * These are the current shader format properties: * - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to * provide shaders for an NDA platform. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to * provide SPIR-V shaders if applicable. - * - SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL`: The app is able to provide - * DXBC shaders if applicable - * `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to * provide DXIL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL`: The app is able to provide - * MSL shaders if applicable. - * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL`: The app is able to + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to * provide Metal shader libraries if applicable. * * With the D3D12 renderer: @@ -979,25 +2142,28 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDevice( * use for all vertex semantics, default is "TEXCOORD". * * \param props the properties to use. - * \returns a GPU context on success or NULL on failure. + * \returns a GPU context on success or NULL on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetGPUDriver + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties */ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( SDL_PropertiesID props); -#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOL "SDL.gpu.device.create.debugmode" -#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOL "SDL.gpu.device.create.preferlowpower" +#define SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN "SDL.gpu.device.create.debugmode" +#define SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN "SDL.gpu.device.create.preferlowpower" #define SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING "SDL.gpu.device.create.name" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SECRET_BOOL "SDL.gpu.device.create.shaders.secret" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOL "SDL.gpu.device.create.shaders.spirv" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOL "SDL.gpu.device.create.shaders.dxbc" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOL "SDL.gpu.device.create.shaders.dxil" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOL "SDL.gpu.device.create.shaders.msl" -#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOL "SDL.gpu.device.create.shaders.metallib" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN "SDL.gpu.device.create.shaders.private" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN "SDL.gpu.device.create.shaders.spirv" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN "SDL.gpu.device.create.shaders.dxbc" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN "SDL.gpu.device.create.shaders.dxil" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN "SDL.gpu.device.create.shaders.msl" +#define SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN "SDL.gpu.device.create.shaders.metallib" #define SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING "SDL.gpu.device.create.d3d12.semantic" /** @@ -1005,70 +2171,132 @@ extern SDL_DECLSPEC SDL_GPUDevice *SDLCALL SDL_CreateGPUDeviceWithProperties( * * \param device a GPU Context to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUDevice */ extern SDL_DECLSPEC void SDLCALL SDL_DestroyGPUDevice(SDL_GPUDevice *device); /** - * Returns the backend used to create this GPU context. + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + */ +extern SDL_DECLSPEC int SDLCALL SDL_GetNumGPUDrivers(void); + +/** + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDriver(int index); + +/** + * Returns the name of the backend used to create this GPU context. * * \param device a GPU context to query. - * \returns an SDL_GPUDriver value, or SDL_GPU_DRIVER_INVALID on error. + * \returns the name of the device's driver, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_GPUDriver SDLCALL SDL_GetGPUDriver(SDL_GPUDevice *device); +extern SDL_DECLSPEC const char * SDLCALL SDL_GetGPUDeviceDriver(SDL_GPUDevice *device); + +/** + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_GPUShaderFormat SDLCALL SDL_GetGPUShaderFormats(SDL_GPUDevice *device); /* State Creation */ /** * Creates a pipeline object to be used in a compute workflow. * - * Shader resource bindings must be authored to follow a particular order. For - * SPIR-V shaders, use the following resource sets: 0: Read-only storage - * textures, followed by read-only storage buffers 1: Write-only storage - * textures, followed by write-only storage buffers 2: Uniform buffers + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Read-only storage textures, followed by read-only storage - * buffers For u registers: Write-only storage textures, followed by - * write-only storage buffers For b registers: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXIL shaders, use the following register order: (t[n], space0): - * Read-only storage textures, followed by read-only storage buffers (u[n], - * space1): Write-only storage textures, followed by write-only storage - * buffers (b[n], space2): Uniform buffers + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers * - * For MSL/metallib, use the following order: For [[buffer]]: Uniform buffers, - * followed by write-only storage buffers, followed by write-only storage - * buffers For [[texture]]: Read-only storage textures, followed by write-only - * storage textures + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. * * \param device a GPU Context. - * \param computePipelineCreateInfo a struct describing the state of the - * requested compute pipeline. - * \returns a compute pipeline object on success, or NULL on failure. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUComputePipeline * \sa SDL_ReleaseGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipelineCreateInfo *computePipelineCreateInfo); + const SDL_GPUComputePipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING "SDL.gpu.computepipeline.create.name" /** * Creates a pipeline object to be used in a graphics workflow. * - * \param device a GPU Context. - * \param pipelineCreateInfo a struct describing the state of the desired - * graphics pipeline. - * \returns a graphics pipeline object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUShader * \sa SDL_BindGPUGraphicsPipeline @@ -1076,26 +2304,36 @@ extern SDL_DECLSPEC SDL_GPUComputePipeline *SDLCALL SDL_CreateGPUComputePipeline */ extern SDL_DECLSPEC SDL_GPUGraphicsPipeline *SDLCALL SDL_CreateGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipelineCreateInfo *pipelineCreateInfo); + const SDL_GPUGraphicsPipelineCreateInfo *createinfo); + +#define SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING "SDL.gpu.graphicspipeline.create.name" /** * Creates a sampler object to be used when binding textures in a graphics * workflow. * - * \param device a GPU Context. - * \param samplerCreateInfo a struct describing the state of the desired - * sampler. - * \returns a sampler object on success, or NULL on failure. + * There are optional properties that can be provided through `props`. These + * are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_BindGPUVertexSamplers * \sa SDL_BindGPUFragmentSamplers - * \sa SDL_ReleaseSampler + * \sa SDL_ReleaseGPUSampler */ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( SDL_GPUDevice *device, - SDL_GPUSamplerCreateInfo *samplerCreateInfo); + const SDL_GPUSamplerCreateInfo *createinfo); + +#define SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING "SDL.gpu.sampler.create.name" /** * Creates a shader to be used when creating a graphics pipeline. @@ -1103,46 +2341,78 @@ extern SDL_DECLSPEC SDL_GPUSampler *SDLCALL SDL_CreateGPUSampler( * Shader resource bindings must be authored to follow a particular order * depending on the shader format. * - * For SPIR-V shaders, use the following resource sets: For vertex shaders: 0: - * Sampled textures, followed by storage textures, followed by storage buffers - * 1: Uniform buffers For fragment shaders: 2: Sampled textures, followed by - * storage textures, followed by storage buffers 3: Uniform buffers + * For SPIR-V shaders, use the following resource sets: * - * For DXBC Shader Model 5_0 shaders, use the following register order: For t - * registers: Sampled textures, followed by storage textures, followed by - * storage buffers For s registers: Samplers with indices corresponding to the - * sampled textures For b registers: Uniform buffers + * For vertex shaders: * - * For DXIL shaders, use the following register order: For vertex shaders: - * (t[n], space0): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space0): Samplers with indices corresponding to the - * sampled textures (b[n], space1): Uniform buffers For pixel shaders: (t[n], - * space2): Sampled textures, followed by storage textures, followed by - * storage buffers (s[n], space2): Samplers with indices corresponding to the - * sampled textures (b[n], space3): Uniform buffers + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers * - * For MSL/metallib, use the following order: For [[texture]]: Sampled - * textures, followed by storage textures For [[sampler]]: Samplers with - * indices corresponding to the sampled textures For [[buffer]]: Uniform - * buffers, followed by storage buffers. Vertex buffer 0 is bound at - * [[buffer(30)]], vertex buffer 1 at [[buffer(29)]], and so on. Rather than - * manually authoring vertex buffer indices, use the [[stage_in]] attribute - * which will automatically use the vertex input information from the - * SDL_GPUPipeline. + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. * * \param device a GPU Context. - * \param shaderCreateInfo a struct describing the state of the desired - * shader. - * \returns a shader object on success, or NULL on failure. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or NULL on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateGPUGraphicsPipeline * \sa SDL_ReleaseGPUShader */ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( SDL_GPUDevice *device, - SDL_GPUShaderCreateInfo *shaderCreateInfo); + const SDL_GPUShaderCreateInfo *createinfo); + +#define SDL_PROP_GPU_SHADER_CREATE_NAME_STRING "SDL.gpu.shader.create.name" /** * Creates a texture object to be used in graphics or compute workflows. @@ -1157,12 +2427,36 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * - * \param device a GPU Context. - * \param textureCreateInfo a struct describing the state of the texture to - * create. - * \returns a texture object on success, or NULL on failure. + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: * - * \since This function is available since SDL 3.0.0. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the texture to create. + * \returns a texture object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture * \sa SDL_DownloadFromGPUTexture @@ -1177,7 +2471,15 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( */ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, - SDL_GPUTextureCreateInfo *textureCreateInfo); + const SDL_GPUTextureCreateInfo *createinfo); + +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT "SDL.gpu.texture.create.d3d12.clear.r" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT "SDL.gpu.texture.create.d3d12.clear.g" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT "SDL.gpu.texture.create.d3d12.clear.b" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT "SDL.gpu.texture.create.d3d12.clear.a" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.texture.create.d3d12.clear.depth" +#define SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.texture.create.d3d12.clear.stencil" +#define SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING "SDL.gpu.texture.create.name" /** * Creates a buffer object to be used in graphics or compute workflows. @@ -1188,35 +2490,63 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( * Note that certain combinations of usage flags are invalid. For example, a * buffer cannot have both the VERTEX and INDEX flags. * - * \param device a GPU Context. - * \param bufferCreateInfo a struct describing the state of the buffer to - * create. - * \returns a buffer object on success, or NULL on failure. + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer * \sa SDL_BindGPUVertexBuffers * \sa SDL_BindGPUIndexBuffer * \sa SDL_BindGPUVertexStorageBuffers * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect * \sa SDL_ReleaseGPUBuffer */ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( SDL_GPUDevice *device, - SDL_GPUBufferCreateInfo *bufferCreateInfo); + const SDL_GPUBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING "SDL.gpu.buffer.create.name" /** * Creates a transfer buffer to be used when uploading to or downloading from * graphics resources. * - * \param device a GPU Context. - * \param transferBufferCreateInfo a struct describing the state of the - * transfer buffer to create. - * \returns a transfer buffer on success, or NULL on failure. + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. * - * \since This function is available since SDL 3.0.0. + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or NULL on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUBuffer * \sa SDL_DownloadFromGPUBuffer @@ -1226,20 +2556,28 @@ extern SDL_DECLSPEC SDL_GPUBuffer *SDLCALL SDL_CreateGPUBuffer( */ extern SDL_DECLSPEC SDL_GPUTransferBuffer *SDLCALL SDL_CreateGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBufferCreateInfo *transferBufferCreateInfo); + const SDL_GPUTransferBufferCreateInfo *createinfo); + +#define SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING "SDL.gpu.transferbuffer.create.name" /* Debug Naming */ /** * Sets an arbitrary string constant to label a buffer. * - * Useful for debugging. + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. * * \param device a GPU Context. * \param buffer a buffer to attach the name to. * \param text a UTF-8 string constant to mark as the name of the buffer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( SDL_GPUDevice *device, @@ -1249,13 +2587,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBufferName( /** * Sets an arbitrary string constant to label a texture. * - * Useful for debugging. + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. * * \param device a GPU Context. * \param texture a texture to attach the name to. * \param text a UTF-8 string constant to mark as the name of the texture. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( SDL_GPUDevice *device, @@ -1267,13 +2612,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUTextureName( * * Useful for debugging. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param text a UTF-8 string constant to insert as the label. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *text); /** @@ -1290,28 +2635,28 @@ extern SDL_DECLSPEC void SDLCALL SDL_InsertGPUDebugLabel( * pass rather than the command buffer. For best results, if you push a debug * group during a pass, always pop it in the same pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \param name a UTF-8 string constant that names the group. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PopGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, const char *name); /** * Ends the most-recently pushed debug group. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushGPUDebugGroup */ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /* Disposal */ @@ -1323,7 +2668,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_PopGPUDebugGroup( * \param device a GPU context. * \param texture a texture to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( SDL_GPUDevice *device, @@ -1332,12 +2677,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTexture( /** * Frees the given sampler as soon as it is safe to do so. * - * You must not reference the texture after calling this function. + * You must not reference the sampler after calling this function. * * \param device a GPU context. * \param sampler a sampler to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( SDL_GPUDevice *device, @@ -1351,7 +2696,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUSampler( * \param device a GPU context. * \param buffer a buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( SDL_GPUDevice *device, @@ -1363,13 +2708,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUBuffer( * You must not reference the transfer buffer after calling this function. * * \param device a GPU context. - * \param transferBuffer a transfer buffer to be destroyed. + * \param transfer_buffer a transfer buffer to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /** * Frees the given compute pipeline as soon as it is safe to do so. @@ -1377,13 +2722,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUTransferBuffer( * You must not reference the compute pipeline after calling this function. * * \param device a GPU context. - * \param computePipeline a compute pipeline to be destroyed. + * \param compute_pipeline a compute pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( SDL_GPUDevice *device, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePipeline *compute_pipeline); /** * Frees the given shader as soon as it is safe to do so. @@ -1393,7 +2738,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUComputePipeline( * \param device a GPU context. * \param shader a shader to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( SDL_GPUDevice *device, @@ -1405,29 +2750,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUShader( * You must not reference the graphics pipeline after calling this function. * * \param device a GPU context. - * \param graphicsPipeline a graphics pipeline to be destroyed. + * \param graphics_pipeline a graphics pipeline to be destroyed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( SDL_GPUDevice *device, - SDL_GPUGraphicsPipeline *graphicsPipeline); - -/* - * COMMAND BUFFERS - * - * Render state is managed via command buffers. - * When setting render state, that state is always local to the command buffer. - * - * Commands only begin execution on the GPU once Submit is called. - * Once the command buffer is submitted, it is no longer valid to use it. - * - * Command buffers are executed in submission order. If you submit command buffer A and then command buffer B - * all commands in A will begin executing before any command in B begins executing. - * - * In multi-threading scenarios, you should acquire and submit a command buffer on the same thread. - * As long as you satisfy this requirement, all functionality related to command buffers is thread-safe. - */ + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Acquire a command buffer. @@ -1437,10 +2766,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( * acquired on. The command buffer should be submitted on the thread it was * acquired on. * - * \param device a GPU context. - * \returns a command buffer. + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. * - * \since This function is available since SDL 3.0.0. + * \param device a GPU context. + * \returns a command buffer, or NULL on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence @@ -1448,118 +2785,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUGraphicsPipeline( extern SDL_DECLSPEC SDL_GPUCommandBuffer *SDLCALL SDL_AcquireGPUCommandBuffer( SDL_GPUDevice *device); -/* - * UNIFORM DATA - * - * Uniforms are for passing data to shaders. - * The uniform data will be constant across all executions of the shader. - * - * There are 4 available uniform slots per shader stage (vertex, fragment, compute). - * Uniform data pushed to a slot on a stage keeps its value throughout the command buffer - * until you call the relevant Push function on that slot again. - * - * For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0, - * push the camera matrix at the start of the command buffer, and that data will be used for every - * subsequent draw call. - * - * It is valid to push uniform data during a render or compute pass. - * - * Uniforms are best for pushing small amounts of data. - * If you are pushing more than a matrix or two per call you should consider using a storage buffer instead. - */ +/* Uniform Data */ /** * Pushes data to a vertex uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the vertex uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the vertex uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUVertexUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a fragment uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the fragment uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the fragment uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUFragmentUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); + Uint32 length); /** * Pushes data to a uniform slot on the command buffer. * * Subsequent draw calls will use this uniform data. * - * \param commandBuffer a command buffer. - * \param slotIndex the uniform slot to push data to. + * \param command_buffer a command buffer. + * \param slot_index the uniform slot to push data to. * \param data client data to write. - * \param dataLengthInBytes the length of the data to write. + * \param length the length of the data to write. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( - SDL_GPUCommandBuffer *commandBuffer, - Uint32 slotIndex, + SDL_GPUCommandBuffer *command_buffer, + Uint32 slot_index, const void *data, - Uint32 dataLengthInBytes); - -/* - * A NOTE ON CYCLING - * - * When using a command buffer, operations do not occur immediately - - * they occur some time after the command buffer is submitted. - * - * When a resource is used in a pending or active command buffer, it is considered to be "bound". - * When a resource is no longer used in any pending or active command buffers, it is considered to be "unbound". - * - * If data resources are bound, it is unspecified when that data will be unbound - * unless you acquire a fence when submitting the command buffer and wait on it. - * However, this doesn't mean you need to track resource usage manually. - * - * All of the functions and structs that involve writing to a resource have a "cycle" bool. - * GPUTransferBuffer, GPUBuffer, and GPUTexture all effectively function as ring buffers on internal resources. - * When cycle is SDL_TRUE, if the resource is bound, the cycle rotates to the next unbound internal resource, - * or if none are available, a new one is created. - * This means you don't have to worry about complex state tracking and synchronization as long as cycling is correctly employed. - * - * For example: you can call MapTransferBuffer, write texture data, UnmapTransferBuffer, and then UploadToTexture. - * The next time you write texture data to the transfer buffer, if you set the cycle param to SDL_TRUE, you don't have - * to worry about overwriting any data that is not yet uploaded. - * - * Another example: If you are using a texture in a render pass every frame, this can cause a data dependency between frames. - * If you set cycle to SDL_TRUE in the ColorAttachmentInfo struct, you can prevent this data dependency. - * - * Cycling will never undefine already bound data. - * When cycling, all data in the resource is considered to be undefined for subsequent commands until that data is written again. - * You must take care not to read undefined data. - * - * Note that when cycling a texture, the entire texture will be cycled, - * even if only part of the texture is used in the call, - * so you must consider the entire texture to contain undefined data after cycling. - * - * You must also take care not to overwrite a section of data that has been referenced in a command without cycling first. - * It is OK to overwrite unreferenced data in a bound resource without cycling, - * but overwriting a section of data that has already been referenced will produce unexpected results. - */ + Uint32 length); /* Graphics State */ @@ -1574,212 +2854,240 @@ extern SDL_DECLSPEC void SDLCALL SDL_PushGPUComputeUniformData( * is called. You cannot begin another render pass, or begin a compute pass or * copy pass until you have ended the render pass. * - * \param commandBuffer a command buffer. - * \param colorAttachmentInfos an array of texture subresources with - * corresponding clear values and load/store ops. - * \param colorAttachmentCount the number of color attachments in the - * colorAttachmentInfos array. - * \param depthStencilAttachmentInfo a texture subresource with corresponding - * clear value and load/store ops, may be - * NULL. + * \param command_buffer a command buffer. + * \param color_target_infos an array of texture subresources with + * corresponding clear values and load/store ops. + * \param num_color_targets the number of color targets in the + * color_target_infos array. + * \param depth_stencil_target_info a texture subresource with corresponding + * clear value and load/store ops, may be + * NULL. * \returns a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPURenderPass */ extern SDL_DECLSPEC SDL_GPURenderPass *SDLCALL SDL_BeginGPURenderPass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUColorAttachmentInfo *colorAttachmentInfos, - Uint32 colorAttachmentCount, - SDL_GPUDepthStencilAttachmentInfo *depthStencilAttachmentInfo); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUColorTargetInfo *color_target_infos, + Uint32 num_color_targets, + const SDL_GPUDepthStencilTargetInfo *depth_stencil_target_info); /** * Binds a graphics pipeline on a render pass to be used in rendering. * * A graphics pipeline must be bound before making any draw calls. * - * \param renderPass a render pass handle. - * \param graphicsPipeline the graphics pipeline to bind. + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUGraphicsPipeline( - SDL_GPURenderPass *renderPass, - SDL_GPUGraphicsPipeline *graphicsPipeline); + SDL_GPURenderPass *render_pass, + SDL_GPUGraphicsPipeline *graphics_pipeline); /** * Sets the current viewport state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param viewport the viewport to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUViewport( - SDL_GPURenderPass *renderPass, - SDL_GPUViewport *viewport); + SDL_GPURenderPass *render_pass, + const SDL_GPUViewport *viewport); /** * Sets the current scissor state on a command buffer. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param scissor the scissor area to set. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetGPUScissor( - SDL_GPURenderPass *renderPass, - SDL_Rect *scissor); + SDL_GPURenderPass *render_pass, + const SDL_Rect *scissor); + +/** + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUBlendConstants( + SDL_GPURenderPass *render_pass, + SDL_FColor blend_constants); + +/** + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetGPUStencilReference( + SDL_GPURenderPass *render_pass, + Uint8 reference); /** * Binds vertex buffers on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param firstBinding the starting bind point for the vertex buffers. - * \param pBindings an array of SDL_GPUBufferBinding structs containing vertex - * buffers and offset values. - * \param bindingCount the number of bindings in the pBindings array. + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstBinding, - SDL_GPUBufferBinding *pBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUBufferBinding *bindings, + Uint32 num_bindings); /** * Binds an index buffer on a command buffer for use with subsequent draw * calls. * - * \param renderPass a render pass handle. - * \param pBinding a pointer to a struct containing an index buffer and - * offset. - * \param indexElementSize whether the index values in the buffer are 16- or - * 32-bit. + * \param render_pass a render pass handle. + * \param binding a pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUIndexBuffer( - SDL_GPURenderPass *renderPass, - SDL_GPUBufferBinding *pBinding, - SDL_GPUIndexElementSize indexElementSize); + SDL_GPURenderPass *render_pass, + const SDL_GPUBufferBinding *binding, + SDL_GPUIndexElementSize index_element_size); /** * Binds texture-sampler pairs for use on the vertex shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the vertex sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the vertex shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage texture to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage texture to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the vertex shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the vertex storage buffer slot to begin binding from. - * \param storageBuffers an array of buffers. - * \param bindingCount the number of buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the vertex storage buffer slot to begin binding from. + * \param storage_buffers an array of buffers. + * \param num_bindings the number of buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUVertexStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Binds texture-sampler pairs for use on the fragment shader. * - * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER_BIT. + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment sampler slot to begin binding from. - * \param textureSamplerBindings an array of texture-sampler binding structs. - * \param bindingCount the number of texture-sampler pairs to bind from the + * \param render_pass a render pass handle. + * \param first_slot the fragment sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler pairs to bind from the * array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentSamplers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTextureSamplerBinding *textureSamplerBindings, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures for use on the fragment shader. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageTextures( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers for use on the fragment shader. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ. * - * \param renderPass a render pass handle. - * \param firstSlot the fragment storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffers. - * \param bindingCount the number of storage buffers to bind from the array. + * \param render_pass a render pass handle. + * \param first_slot the fragment storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffers. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( - SDL_GPURenderPass *renderPass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPURenderPass *render_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /* Drawing */ @@ -1789,100 +3097,101 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUFragmentStorageBuffers( * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param indexCount the number of vertices to draw per instance. - * \param instanceCount the number of instances to draw. - * \param firstIndex the starting index within the index buffer. - * \param vertexOffset value added to vertex index before indexing into the - * vertex buffer. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 indexCount, - Uint32 instanceCount, - Uint32 firstIndex, - Sint32 vertexOffset, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_indices, + Uint32 num_instances, + Uint32 first_index, + Sint32 vertex_offset, + Uint32 first_instance); /** * Draws data using bound graphics state. * * You must not call this function before binding a graphics pipeline. * - * Note that the `firstVertex` and `firstInstance` parameters are NOT + * Note that the `first_vertex` and `first_instance` parameters are NOT * compatible with built-in vertex/instance ID variables in shaders (for - * example, SV_VertexID). If your shader depends on these variables, the - * correlating draw call parameter MUST be 0. + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. * - * \param renderPass a render pass handle. - * \param vertexCount the number of vertices to draw. - * \param instanceCount the number of instances that will be drawn. - * \param firstVertex the index of the first vertex to draw. - * \param firstInstance the ID of the first instance to draw. + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitives( - SDL_GPURenderPass *renderPass, - Uint32 vertexCount, - Uint32 instanceCount, - Uint32 firstVertex, - Uint32 firstInstance); + SDL_GPURenderPass *render_pass, + Uint32 num_vertices, + Uint32 num_instances, + Uint32 first_vertex, + Uint32 first_instance); /** * Draws data using bound graphics state and with draw parameters set from a * buffer. * - * The buffer layout should match the layout of SDL_GPUIndirectDrawCommand. - * You must not call this function before binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Draws data using bound graphics state with an index buffer enabled and with * draw parameters set from a buffer. * - * The buffer layout should match the layout of - * SDL_GPUIndexedIndirectDrawCommand. You must not call this function before - * binding a graphics pipeline. + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * \param buffer a buffer containing draw parameters. - * \param offsetInBytes the offset to start reading from the draw buffer. - * \param drawCount the number of draw parameter sets that should be read from - * the draw buffer. - * \param stride the byte stride between sets of draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( - SDL_GPURenderPass *renderPass, + SDL_GPURenderPass *render_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes, - Uint32 drawCount, - Uint32 stride); + Uint32 offset, + Uint32 draw_count); /** * Ends the given render pass. @@ -1890,12 +3199,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DrawGPUIndexedPrimitivesIndirect( * All bound graphics state on the render pass command buffer is unset. The * render pass handle is now invalid. * - * \param renderPass a render pass handle. + * \param render_pass a render pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( - SDL_GPURenderPass *renderPass); + SDL_GPURenderPass *render_pass); /* Compute Pass */ @@ -1903,89 +3212,115 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPURenderPass( * Begins a compute pass on a command buffer. * * A compute pass is defined by a set of texture subresources and buffers that - * will be written to by compute pipelines. These textures and buffers must - * have been created with the COMPUTE_STORAGE_WRITE bit. All operations - * related to compute pipelines must take place inside of a compute pass. You - * must not begin another compute pass, or a render pass or copy pass before - * ending the compute pass. + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. * - * A VERY IMPORTANT NOTE Textures and buffers bound as write-only MUST NOT be - * read from during the compute pass. Doing so will result in undefined - * behavior. If your compute work requires reading the output from a previous - * dispatch, you MUST end the current compute pass and begin a new one before - * you can safely access the data. + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! * - * \param commandBuffer a command buffer. - * \param storageTextureBindings an array of writeable storage texture binding - * structs. - * \param storageTextureBindingCount the number of storage textures to bind - * from the array. - * \param storageBufferBindings an array of writeable storage buffer binding - * structs. - * \param storageBufferBindingCount the number of storage buffers to bind from - * the array. + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. * \returns a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EndGPUComputePass */ extern SDL_DECLSPEC SDL_GPUComputePass *SDLCALL SDL_BeginGPUComputePass( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUStorageTextureWriteOnlyBinding *storageTextureBindings, - Uint32 storageTextureBindingCount, - SDL_GPUStorageBufferWriteOnlyBinding *storageBufferBindings, - Uint32 storageBufferBindingCount); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUStorageTextureReadWriteBinding *storage_texture_bindings, + Uint32 num_storage_texture_bindings, + const SDL_GPUStorageBufferReadWriteBinding *storage_buffer_bindings, + Uint32 num_storage_buffer_bindings); /** * Binds a compute pipeline on a command buffer for use in compute dispatch. * - * \param computePass a compute pass handle. - * \param computePipeline a compute pipeline to bind. + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputePipeline( - SDL_GPUComputePass *computePass, - SDL_GPUComputePipeline *computePipeline); + SDL_GPUComputePass *compute_pass, + SDL_GPUComputePipeline *compute_pipeline); + +/** + * Binds texture-sampler pairs for use on the compute shader. + * + * The textures must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. + * + * \param compute_pass a compute pass handle. + * \param first_slot the compute sampler slot to begin binding from. + * \param texture_sampler_bindings an array of texture-sampler binding + * structs. + * \param num_bindings the number of texture-sampler bindings to bind from the + * array. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeSamplers( + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + const SDL_GPUTextureSamplerBinding *texture_sampler_bindings, + Uint32 num_bindings); /** * Binds storage textures as readonly for use on the compute pipeline. * * These textures must have been created with - * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage texture slot to begin binding from. - * \param storageTextures an array of storage textures. - * \param bindingCount the number of storage textures to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage texture slot to begin binding from. + * \param storage_textures an array of storage textures. + * \param num_bindings the number of storage textures to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageTextures( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUTexture **storageTextures, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUTexture *const *storage_textures, + Uint32 num_bindings); /** * Binds storage buffers as readonly for use on the compute pipeline. * * These buffers must have been created with - * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ_BIT. + * SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ. * - * \param computePass a compute pass handle. - * \param firstSlot the compute storage buffer slot to begin binding from. - * \param storageBuffers an array of storage buffer binding structs. - * \param bindingCount the number of storage buffers to bind from the array. + * \param compute_pass a compute pass handle. + * \param first_slot the compute storage buffer slot to begin binding from. + * \param storage_buffers an array of storage buffer binding structs. + * \param num_bindings the number of storage buffers to bind from the array. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( - SDL_GPUComputePass *computePass, - Uint32 firstSlot, - SDL_GPUBuffer **storageBuffers, - Uint32 bindingCount); + SDL_GPUComputePass *compute_pass, + Uint32 first_slot, + SDL_GPUBuffer *const *storage_buffers, + Uint32 num_bindings); /** * Dispatches compute work. @@ -1997,21 +3332,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_BindGPUComputeStorageBuffers( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. - * \param groupCountX number of local workgroups to dispatch in the X - * dimension. - * \param groupCountY number of local workgroups to dispatch in the Y - * dimension. - * \param groupCountZ number of local workgroups to dispatch in the Z - * dimension. + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( - SDL_GPUComputePass *computePass, - Uint32 groupCountX, - Uint32 groupCountY, - Uint32 groupCountZ); + SDL_GPUComputePass *compute_pass, + Uint32 groupcount_x, + Uint32 groupcount_y, + Uint32 groupcount_z); /** * Dispatches compute work with parameters set from a buffer. @@ -2025,16 +3360,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUCompute( * guarantee of which order the writes will occur. If the write order matters, * you MUST end the compute pass and begin another one. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * \param buffer a buffer containing dispatch parameters. - * \param offsetInBytes the offset to start reading from the dispatch buffer. + * \param offset the offset to start reading from the dispatch buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( - SDL_GPUComputePass *computePass, + SDL_GPUComputePass *compute_pass, SDL_GPUBuffer *buffer, - Uint32 offsetInBytes); + Uint32 offset); /** * Ends the current compute pass. @@ -2042,12 +3377,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_DispatchGPUComputeIndirect( * All bound compute state on the command buffer is unset. The compute pass * handle is now invalid. * - * \param computePass a compute pass handle. + * \param compute_pass a compute pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( - SDL_GPUComputePass *computePass); + SDL_GPUComputePass *compute_pass); /* TransferBuffer Data */ @@ -2057,28 +3392,29 @@ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUComputePass( * You must unmap the transfer buffer before encoding upload commands. * * \param device a GPU context. - * \param transferBuffer a transfer buffer. - * \param cycle if SDL_TRUE, cycles the transfer buffer if it is bound. - * \returns the address of the mapped transfer buffer memory. + * \param transfer_buffer a transfer buffer. + * \param cycle if true, cycles the transfer buffer if it is already bound. + * \returns the address of the mapped transfer buffer memory, or NULL on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void *SDLCALL SDL_MapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer, - SDL_bool cycle); + SDL_GPUTransferBuffer *transfer_buffer, + bool cycle); /** * Unmaps a previously mapped transfer buffer. * * \param device a GPU context. - * \param transferBuffer a previously mapped transfer buffer. + * \param transfer_buffer a previously mapped transfer buffer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( SDL_GPUDevice *device, - SDL_GPUTransferBuffer *transferBuffer); + SDL_GPUTransferBuffer *transfer_buffer); /* Copy Pass */ @@ -2089,13 +3425,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnmapGPUTransferBuffer( * inside a copy pass. You must not begin another copy pass, or a render pass * or compute pass before ending the copy pass. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. * \returns a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); /** * Uploads data from a transfer buffer to a texture. @@ -2106,21 +3442,19 @@ extern SDL_DECLSPEC SDL_GPUCopyPass *SDLCALL SDL_BeginGPUCopyPass( * You must align the data in the transfer buffer to a multiple of the texel * size of the texture format. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with image layout information. * \param destination the destination texture region. - * \param cycle if SDL_TRUE, cycles the texture if the texture is bound, - * otherwise overwrites the data. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureTransferInfo *source, - SDL_GPUTextureRegion *destination, - SDL_bool cycle); - -/* Uploads data from a TransferBuffer to a Buffer. */ + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureTransferInfo *source, + const SDL_GPUTextureRegion *destination, + bool cycle); /** * Uploads data from a transfer buffer to a buffer. @@ -2128,19 +3462,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUTexture( * The upload occurs on the GPU timeline. You may assume that the upload has * finished in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source transfer buffer with offset. * \param destination the destination buffer with offset and size. - * \param cycle if SDL_TRUE, cycles the buffer if it is bound, otherwise + * \param cycle if true, cycles the buffer if it is already bound, otherwise * overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUTransferBufferLocation *source, - SDL_GPUBufferRegion *destination, - SDL_bool cycle); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTransferBufferLocation *source, + const SDL_GPUBufferRegion *destination, + bool cycle); /** * Performs a texture-to-texture copy. @@ -2148,27 +3482,25 @@ extern SDL_DECLSPEC void SDLCALL SDL_UploadToGPUBuffer( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source a source texture region. * \param destination a destination texture region. * \param w the width of the region to copy. * \param h the height of the region to copy. * \param d the depth of the region to copy. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination + * \param cycle if true, cycles the destination texture if the destination * texture is bound, otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureLocation *source, - SDL_GPUTextureLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureLocation *source, + const SDL_GPUTextureLocation *destination, Uint32 w, Uint32 h, Uint32 d, - SDL_bool cycle); - -/* Copies data from a buffer to a buffer. */ + bool cycle); /** * Performs a buffer-to-buffer copy. @@ -2176,21 +3508,21 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUTextureToTexture( * This copy occurs on the GPU timeline. You may assume the copy has finished * in subsequent commands. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the buffer and offset to copy from. * \param destination the buffer and offset to copy to. * \param size the length of the buffer to copy. - * \param cycle if SDL_TRUE, cycles the destination buffer if it is bound, + * \param cycle if true, cycles the destination buffer if it is already bound, * otherwise overwrites the data. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferLocation *source, - SDL_GPUBufferLocation *destination, + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferLocation *source, + const SDL_GPUBufferLocation *destination, Uint32 size, - SDL_bool cycle); + bool cycle); /** * Copies data from a texture to a transfer buffer on the GPU timeline. @@ -2198,17 +3530,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUBufferToBuffer( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source texture region. * \param destination the destination transfer buffer with image layout * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( - SDL_GPUCopyPass *copyPass, - SDL_GPUTextureRegion *source, - SDL_GPUTextureTransferInfo *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUTextureRegion *source, + const SDL_GPUTextureTransferInfo *destination); /** * Copies data from a buffer to a transfer buffer on the GPU timeline. @@ -2216,39 +3548,39 @@ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUTexture( * This data is not guaranteed to be copied until the command buffer fence is * signaled. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * \param source the source buffer with offset and size. * \param destination the destination transfer buffer with offset. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer( - SDL_GPUCopyPass *copyPass, - SDL_GPUBufferRegion *source, - SDL_GPUTransferBufferLocation *destination); + SDL_GPUCopyPass *copy_pass, + const SDL_GPUBufferRegion *source, + const SDL_GPUTransferBufferLocation *destination); /** * Ends the current copy pass. * - * \param copyPass a copy pass handle. + * \param copy_pass a copy pass handle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EndGPUCopyPass( - SDL_GPUCopyPass *copyPass); + SDL_GPUCopyPass *copy_pass); /** * Generates mipmaps for the given texture. * * This function must not be called inside of any pass. * - * \param commandBuffer a commandBuffer. + * \param command_buffer a command_buffer. * \param texture a texture with more than 1 mip level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, + SDL_GPUCommandBuffer *command_buffer, SDL_GPUTexture *texture); /** @@ -2256,23 +3588,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GenerateMipmapsForGPUTexture( * * This function must not be called inside of any pass. * - * \param commandBuffer a command buffer. - * \param source the texture region to copy from. - * \param destination the texture region to copy to. - * \param flipMode the flip mode for the source texture region. - * \param filterMode the filter mode that will be used when blitting. - * \param cycle if SDL_TRUE, cycles the destination texture if the destination - * texture is bound, otherwise overwrites the data. + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( - SDL_GPUCommandBuffer *commandBuffer, - SDL_GPUBlitRegion *source, - SDL_GPUBlitRegion *destination, - SDL_FlipMode flipMode, - SDL_GPUFilter filterMode, - SDL_bool cycle); + SDL_GPUCommandBuffer *command_buffer, + const SDL_GPUBlitInfo *info); /* Submission/Presentation */ @@ -2283,17 +3606,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_BlitGPUTexture( * * \param device a GPU context. * \param window an SDL_Window. - * \param swapchainComposition the swapchain composition to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition); + SDL_GPUSwapchainComposition swapchain_composition); /** * Determines whether a presentation mode is supported by the window. @@ -2302,40 +3625,46 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUSwapchainComposition( * * \param device a GPU context. * \param window an SDL_Window. - * \param presentMode the presentation mode to check. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported (or on error). + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowSupportsGPUPresentMode( +extern SDL_DECLSPEC bool SDLCALL SDL_WindowSupportsGPUPresentMode( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUPresentMode presentMode); + SDL_GPUPresentMode present_mode); /** * Claims a window, creating a swapchain structure for it. * * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created * the window. * * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain - * parameters, you must call SetSwapchainParameters after claiming the window. + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. * * \param device a GPU context. * \param window an SDL_Window. - * \returns SDL_TRUE on success, otherwise SDL_FALSE. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. * - * \sa SDL_AcquireGPUSwapchainTexture + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_ReleaseWindowFromGPUDevice * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( +extern SDL_DECLSPEC bool SDLCALL SDL_ClaimWindowForGPUDevice( SDL_GPUDevice *device, SDL_Window *window); @@ -2345,7 +3674,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClaimWindowForGPUDevice( * \param device a GPU context. * \param window an SDL_Window that has been claimed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice */ @@ -2366,29 +3695,61 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseWindowFromGPUDevice( * * \param device a GPU context. * \param window an SDL_Window that has been claimed. - * \param swapchainComposition the desired composition of the swapchain. - * \param presentMode the desired present mode for the swapchain. - * \returns SDL_TRUE if successful, SDL_FALSE on error. + * \param swapchain_composition the desired composition of the swapchain. + * \param present_mode the desired present mode for the swapchain. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowSupportsGPUPresentMode * \sa SDL_WindowSupportsGPUSwapchainComposition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetGPUSwapchainParameters( +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUSwapchainParameters( SDL_GPUDevice *device, SDL_Window *window, - SDL_GPUSwapchainComposition swapchainComposition, - SDL_GPUPresentMode presentMode); + SDL_GPUSwapchainComposition swapchain_composition, + SDL_GPUPresentMode present_mode); + +/** + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture pointer with NULL, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetGPUAllowedFramesInFlight( + SDL_GPUDevice *device, + Uint32 allowed_frames_in_flight); /** * Obtains the texture format of the swapchain for the given window. * + * Note that this format can change if the swapchain parameters change. + * * \param device a GPU context. * \param window an SDL_Window that has been claimed. * \returns the texture format of the swapchain. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureFormat( SDL_GPUDevice *device, @@ -2400,28 +3761,118 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma * When a swapchain texture is acquired on a command buffer, it will * automatically be submitted for presentation when the command buffer is * submitted. The swapchain texture should only be referenced by the command - * buffer used to acquire it. May return NULL under certain conditions. This - * is not necessarily an error. This texture is managed by the implementation - * and must not be freed by the user. You MUST NOT call this function from any - * thread other than the one that created the window. + * buffer used to acquire it. * - * \param commandBuffer a command buffer. + * This function will fill the swapchain texture handle with NULL if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. * \param window a window that has been claimed. - * \param pWidth a pointer filled in with the swapchain width. - * \param pHeight a pointer filled in with the swapchain height. - * \returns a swapchain texture. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ClaimWindowForGPUDevice * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight */ -extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( - SDL_GPUCommandBuffer *commandBuffer, +extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, SDL_Window *window, - Uint32 *pWidth, - Uint32 *pHeight); + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); + +/** + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUSwapchain( + SDL_GPUDevice *device, + SDL_Window *window); + +/** + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with NULL in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the pointer is NULL before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a pointer filled in with the swapchain + * texture width, may be NULL. + * \param swapchain_texture_height a pointer filled in with the swapchain + * texture height, may be NULL. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitAndAcquireGPUSwapchainTexture( + SDL_GPUCommandBuffer *command_buffer, + SDL_Window *window, + SDL_GPUTexture **swapchain_texture, + Uint32 *swapchain_texture_width, + Uint32 *swapchain_texture_height); /** * Submits a command buffer so its commands can be processed on the GPU. @@ -2433,16 +3884,19 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_AcquireGPUSwapchainTexture( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( - SDL_GPUCommandBuffer *commandBuffer); +extern SDL_DECLSPEC bool SDLCALL SDL_SubmitGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Submits a command buffer so its commands can be processed on the GPU, and @@ -2456,63 +3910,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_SubmitGPUCommandBuffer( * All commands in the submission are guaranteed to begin executing before any * command in a subsequent submission begins executing. * - * \param commandBuffer a command buffer. - * \returns a fence associated with the command buffer. + * \param command_buffer a command buffer. + * \returns a fence associated with the command buffer, or NULL on failure; + * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture * \sa SDL_AcquireGPUSwapchainTexture * \sa SDL_SubmitGPUCommandBuffer * \sa SDL_ReleaseGPUFence */ extern SDL_DECLSPEC SDL_GPUFence *SDLCALL SDL_SubmitGPUCommandBufferAndAcquireFence( - SDL_GPUCommandBuffer *commandBuffer); + SDL_GPUCommandBuffer *command_buffer); + +/** + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_CancelGPUCommandBuffer( + SDL_GPUCommandBuffer *command_buffer); /** * Blocks the thread until the GPU is completely idle. * * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitForGPUFences */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUIdle( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUIdle( SDL_GPUDevice *device); /** * Blocks the thread until the given fences are signaled. * * \param device a GPU context. - * \param waitAll if 0, wait for any fence to be signaled, if 1, wait for all - * fences to be signaled. - * \param pFences an array of fences to wait on. - * \param fenceCount the number of fences in the pFences array. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence * \sa SDL_WaitForGPUIdle */ -extern SDL_DECLSPEC void SDLCALL SDL_WaitForGPUFences( +extern SDL_DECLSPEC bool SDLCALL SDL_WaitForGPUFences( SDL_GPUDevice *device, - SDL_bool waitAll, - SDL_GPUFence **pFences, - Uint32 fenceCount); + bool wait_all, + SDL_GPUFence *const *fences, + Uint32 num_fences); /** * Checks the status of a fence. * * \param device a GPU context. * \param fence a fence. - * \returns SDL_TRUE if the fence is signaled, SDL_FALSE if it is not. + * \returns true if the fence is signaled, false if it is not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( +extern SDL_DECLSPEC bool SDLCALL SDL_QueryGPUFence( SDL_GPUDevice *device, SDL_GPUFence *fence); @@ -2522,7 +4007,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_QueryGPUFence( * \param device a GPU context. * \param fence a fence. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SubmitGPUCommandBufferAndAcquireFence */ @@ -2535,15 +4020,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence( /** * Obtains the texel block size for a texture format. * - * \param textureFormat the texture format you want to know the texel size of. + * \param format the texture format you want to know the texel size of. * \returns the texel block size of the texture format. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UploadToGPUTexture */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( - SDL_GPUTextureFormat textureFormat); + SDL_GPUTextureFormat format); /** * Determines whether a texture format is supported for a given type and @@ -2555,9 +4040,9 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GPUTextureFormatTexelBlockSize( * \param usage a bitmask of all usage scenarios to check. * \returns whether the texture format is supported for this type and usage. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsFormat( SDL_GPUDevice *device, SDL_GPUTextureFormat format, SDL_GPUTextureType type, @@ -2568,15 +4053,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsFormat( * * \param device a GPU context. * \param format the texture format to check. - * \param sampleCount the sample count to check. + * \param sample_count the sample count to check. * \returns a hardware-specific version of min(preferred, possible). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( +extern SDL_DECLSPEC bool SDLCALL SDL_GPUTextureSupportsSampleCount( SDL_GPUDevice *device, SDL_GPUTextureFormat format, - SDL_GPUSampleCount sampleCount); + SDL_GPUSampleCount sample_count); + +/** + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_CalculateGPUTextureFormatSize( + SDL_GPUTextureFormat format, + Uint32 width, + Uint32 height, + Uint32 depth_or_layer_count); #ifdef SDL_PLATFORM_GDK @@ -2589,7 +4091,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GPUTextureSupportsSampleCount( * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ @@ -2604,7 +4106,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendGPU(SDL_GPUDevice *device); * * \param device a GPU context. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h index 285b237..e2f32ff 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_guid.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,13 +26,14 @@ * * A GUID is a 128-bit value that represents something that is uniquely * identifiable by this value: "globally unique." + * + * SDL provides functions to convert a GUID to/from a string. */ #ifndef SDL_guid_h_ #define SDL_guid_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -55,7 +56,7 @@ extern "C" { * GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs on different operating systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_GUID { Uint8 data[16]; @@ -70,7 +71,7 @@ typedef struct SDL_GUID { * \param pszGUID buffer in which to write the ASCII string. * \param cbGUID the size of pszGUID, should be at least 33 bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StringToGUID */ @@ -86,7 +87,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, * \param pchGUID string containing an ASCII representation of a GUID. * \returns a SDL_GUID structure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GUIDToString */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h index 95446fe..a45335b 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_haptic.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -66,7 +66,7 @@ * Complete example: * * ```c - * SDL_bool test_haptic(SDL_Joystick *joystick) + * bool test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; * SDL_HapticEffect effect; @@ -74,12 +74,12 @@ * * // Open the device * haptic = SDL_OpenHapticFromJoystick(joystick); - * if (haptic == NULL) return SDL_FALSE; // Most likely joystick isn't haptic + * if (haptic == NULL) return false; // Most likely joystick isn't haptic * * // See if it can do sine waves * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) { * SDL_CloseHaptic(haptic); // No sine effect - * return SDL_FALSE; + * return false; * } * * // Create the effect @@ -106,7 +106,7 @@ * // Close the device * SDL_CloseHaptic(haptic); * - * return SDL_TRUE; // Success + * return true; // Success * } * ``` * @@ -139,15 +139,14 @@ extern "C" { */ /** - * \typedef SDL_Haptic + * The haptic structure used to identify an SDL haptic. * - * The haptic structure used to identify an SDL haptic. + * \since This struct is available since SDL 3.2.0. * - * \sa SDL_OpenHaptic - * \sa SDL_OpenHapticFromJoystick - * \sa SDL_CloseHaptic + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic */ -struct SDL_Haptic; typedef struct SDL_Haptic SDL_Haptic; @@ -168,7 +167,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Constant haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -179,7 +178,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates sine waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -190,7 +189,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates square waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -201,7 +200,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates triangular waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -212,7 +211,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth up waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -223,7 +222,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Periodic haptic effect that simulates saw tooth down waves. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticPeriodic */ @@ -234,7 +233,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Ramp haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticRamp */ @@ -246,7 +245,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates a spring. Effect is based on the * axes position. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -258,7 +257,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -270,7 +269,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -282,7 +281,7 @@ typedef struct SDL_Haptic SDL_Haptic; * Condition haptic effect that simulates friction. Effect is based on the * axes movement. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticCondition */ @@ -293,19 +292,31 @@ typedef struct SDL_Haptic SDL_Haptic; * * Haptic effect for direct control over high/low frequency motors. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticLeftRight */ #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** @@ -313,7 +324,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * User defined custom haptic effect. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_HAPTIC_CUSTOM (1u<<15) @@ -326,7 +337,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting the global gain. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticGain */ @@ -337,7 +348,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports setting autocenter. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SetHapticAutocenter */ @@ -348,7 +359,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Device supports querying effect status. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus */ @@ -359,7 +370,7 @@ typedef struct SDL_Haptic SDL_Haptic; * * Devices supports being paused. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_PauseHaptic * \sa SDL_ResumeHaptic @@ -375,7 +386,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses polar coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -384,7 +395,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses cartesian coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -393,7 +404,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Uses spherical coordinates for the direction. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -405,7 +416,7 @@ typedef struct SDL_Haptic SDL_Haptic; * This provides better compatibility across platforms and devices as SDL will * guess the correct axis. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_HapticDirection */ @@ -422,7 +433,7 @@ typedef struct SDL_Haptic SDL_Haptic; /** * Used to play a device an infinite number of times. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect */ @@ -523,7 +534,7 @@ typedef struct SDL_Haptic SDL_Haptic; * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN @@ -547,7 +558,7 @@ typedef struct SDL_HapticDirection * A constant effect applies a constant force in the specified direction to * the joystick. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect @@ -629,7 +640,7 @@ typedef struct SDL_HapticConstant * \| \| \| \| \| \| \| * ``` * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE @@ -685,7 +696,7 @@ typedef struct SDL_HapticPeriodic * SDL_HapticDirection diagram for which side is positive and which is * negative. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticDirection * \sa SDL_HAPTIC_SPRING @@ -699,7 +710,7 @@ typedef struct SDL_HapticCondition /* Header */ Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ - SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ + SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ Uint32 length; /**< Duration of the effect. */ @@ -728,7 +739,7 @@ typedef struct SDL_HapticCondition * effects get added to the ramp effect making the effect become quadratic * instead of linear. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect @@ -767,7 +778,7 @@ typedef struct SDL_HapticRamp * motors, commonly found in modern game controllers. The small (right) motor * is high frequency, and the large (left) motor is low frequency. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HapticEffect @@ -797,7 +808,7 @@ typedef struct SDL_HapticLeftRight * If channels is one, the effect is rotated using the defined direction. * Otherwise it uses the samples in data for the different axes. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HAPTIC_CUSTOM * \sa SDL_HapticEffect @@ -892,7 +903,7 @@ typedef struct SDL_HapticCustom * Note either the attack_level or the fade_level may be above the actual * effect level. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic @@ -921,7 +932,7 @@ typedef union SDL_HapticEffect * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_HapticID; @@ -937,7 +948,7 @@ typedef Uint32 SDL_HapticID; * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -953,7 +964,7 @@ extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticName * \sa SDL_OpenHaptic @@ -974,7 +985,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID ins * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_GetHaptics @@ -993,7 +1004,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id * \returns an SDL_Haptic on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id); @@ -1004,7 +1015,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instan * \returns the instance ID of the specified haptic device on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); @@ -1016,7 +1027,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); * this function returns NULL; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticNameForID */ @@ -1025,13 +1036,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic); /** * Query whether or not the current mouse has haptic capabilities. * - * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't. + * \returns true if the mouse is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromMouse */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void); /** * Try to open a haptic device from the current mouse. @@ -1039,7 +1050,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsMouseHaptic(void); * \returns the haptic device identifier or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsMouseHaptic @@ -1050,13 +1061,13 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void); * Query if a joystick has haptic features. * * \param joystick the SDL_Joystick to test for haptic capabilities. - * \returns SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't. + * \returns true if the joystick is haptic or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHapticFromJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick); /** * Open a haptic device for use from a joystick device. @@ -1073,7 +1084,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick * \returns a valid haptic device identifier on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseHaptic * \sa SDL_IsJoystickHaptic @@ -1085,7 +1096,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick * * \param haptic the SDL_Haptic device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenHaptic */ @@ -1102,7 +1113,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic); * \returns the number of effects the haptic device can store or a negative * error code on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffectsPlaying * \sa SDL_GetHapticFeatures @@ -1118,7 +1129,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic); * \returns the number of effects the haptic device can play at the same time * or -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMaxHapticEffects * \sa SDL_GetHapticFeatures @@ -1132,7 +1143,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HapticEffectSupported * \sa SDL_GetMaxHapticEffects @@ -1149,7 +1160,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); * \returns the number of axes on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); @@ -1158,14 +1169,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic); * * \param haptic the SDL_Haptic device to query. * \param effect the desired effect to query. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, const SDL_HapticEffect *effect); /** * Create a new haptic effect on a specified device. @@ -1176,7 +1187,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *hapti * \returns the ID of the effect on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyHapticEffect * \sa SDL_RunHapticEffect @@ -1196,15 +1207,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const * \param effect the identifier of the effect to update. * \param data an SDL_HapticEffect structure containing the new effect * properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect * \sa SDL_RunHapticEffect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data); /** * Run the haptic effect on its associated haptic device. @@ -1219,31 +1230,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, * \param effect the ID of the haptic effect to run. * \param iterations the number of iterations to run the effect; use * `SDL_HAPTIC_INFINITY` to repeat forever. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticEffectStatus * \sa SDL_StopHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); +extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations); /** * Stop the haptic effect on its associated haptic device. * * \param haptic the SDL_Haptic device to stop the effect on. * \param effect the ID of the haptic effect to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int effect); /** * Destroy a haptic effect on the device. @@ -1254,7 +1265,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, in * \param haptic the SDL_Haptic device to destroy the effect on. * \param effect the ID of the haptic effect to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateHapticEffect */ @@ -1267,14 +1278,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int * * \param haptic the SDL_Haptic device to query for the effect status on. * \param effect the ID of the haptic effect to query its status. - * \returns SDL_TRUE if it is playing, SDL_FALSE if it isn't playing or haptic - * status isn't supported. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, int effect); /** * Set the global gain of the specified haptic device. @@ -1289,14 +1300,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *hapti * \param haptic the SDL_Haptic device to set the gain on. * \param gain value to set the gain to, should be between 0 and 100 (0 - * 100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain); /** * Set the global autocenter of the device. @@ -1308,14 +1319,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int g * * \param haptic the SDL_Haptic device to set autocentering on. * \param autocenter value to set autocenter to (0-100). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHapticFeatures */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int autocenter); /** * Pause a haptic device. @@ -1327,14 +1338,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, * can cause all sorts of weird errors. * * \param haptic the SDL_Haptic device to pause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResumeHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); /** * Resume a haptic device. @@ -1342,55 +1353,55 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic); * Call to unpause after SDL_PauseHaptic(). * * \param haptic the SDL_Haptic device to unpause. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PauseHaptic */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic); /** * Stop all the currently playing effects on a haptic device. * * \param haptic the SDL_Haptic device to stop. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RunHapticEffect * \sa SDL_StopHapticEffects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic); /** * Check whether rumble is supported on a haptic device. * * \param haptic haptic device to check for rumble support. - * \returns SDL_TRUE if the effect is supported or SDL_FALSE if it isn't. + * \returns true if the effect is supported or false if it isn't. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic); /** * Initialize a haptic device for simple rumble playback. * * \param haptic the haptic device to initialize for simple rumble playback. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble * \sa SDL_StopHapticRumble * \sa SDL_HapticRumbleSupported */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); /** * Run a simple rumble effect on a haptic device. @@ -1398,28 +1409,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic); * \param haptic the haptic device to play the rumble effect on. * \param strength strength of the rumble to play as a 0-1 float value. * \param length length of the rumble to play in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitHapticRumble * \sa SDL_StopHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); +extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length); /** * Stop the simple rumble on a haptic device. * * \param haptic the haptic device to stop the rumble effect on. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PlayHapticRumble */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); +extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticRumble(SDL_Haptic *haptic); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h index 66bea9d..131b037 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hidapi.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -65,14 +65,14 @@ extern "C" { /** * An opaque handle representing an open HID device. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device SDL_hid_device; /** * HID underlying bus types. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_hid_bus_type { /** Unknown bus type */ @@ -107,7 +107,7 @@ typedef enum SDL_hid_bus_type { /** * Information about a connected HID device * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_hid_device_info { @@ -169,7 +169,7 @@ typedef struct SDL_hid_device_info * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_exit */ @@ -184,7 +184,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_init */ @@ -205,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void); * \returns a change counter that is incremented with each potential device * change, or 0 if device change detection isn't available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_enumerate */ @@ -233,7 +233,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); * in the case of failure. Free this linked list by calling * SDL_hid_free_enumeration(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_hid_device_change_count */ @@ -247,7 +247,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned sho * \param devs pointer to a list of struct_device returned from * SDL_hid_enumerate(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs); @@ -265,7 +265,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); @@ -279,7 +279,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_ * \returns a pointer to a SDL_hid_device object on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); @@ -306,7 +306,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path) * \returns the actual number of bytes written and -1 on on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne * SDL_GetError() for more information. If no packet was available to * be read within the timeout period, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds); @@ -348,7 +348,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign * be read and the handle is in non-blocking mode, this function * returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -367,7 +367,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock); @@ -392,7 +392,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int * \returns the actual number of bytes written and -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length); @@ -415,7 +415,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -438,7 +438,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, * still in the first byte), or -1 on on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); @@ -449,7 +449,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, un * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); @@ -462,7 +462,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev); * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -475,7 +475,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device * * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -488,7 +488,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen); @@ -502,7 +502,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); @@ -514,7 +514,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, * on failure; call SDL_GetError() for more information. This struct * is valid until the device is closed with SDL_hid_close(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); @@ -530,18 +530,18 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi * \returns the number of bytes actually copied or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * - * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan. + * \param active true to start the scan, false to stop the scan. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active); +extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h index 8433240..8f2d074 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_hints.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,8 +22,6 @@ /** * # CategoryHints * - * Official documentation for SDL configuration variables - * * This file contains functions to set and get configuration hints, as well as * listing each of them alphabetically. * @@ -63,7 +61,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" @@ -83,7 +81,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" @@ -98,10 +96,27 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" +/** + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_ANDROID_LOW_LATENCY_AUDIO "SDL_ANDROID_LOW_LATENCY_AUDIO" + /** * A variable to control whether we trap the Android back button to handle it * manually. @@ -121,7 +136,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" @@ -137,7 +152,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_ID "SDL_APP_ID" @@ -155,7 +170,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APP_NAME "SDL_APP_NAME" @@ -178,7 +193,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" @@ -193,7 +208,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" @@ -201,16 +216,58 @@ extern "C" { * Specify the default ALSA audio device name. * * This variable is a specific audio device to open when the "default" audio - * device is used. By default if 4 channel audio is requested, the - * "plug:surround40" device will be opened and if 6 channel audio is requested - * the "plug:surround51" device will be opened. + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE */ #define SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE "SDL_AUDIO_ALSA_DEFAULT_DEVICE" +/** + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE "SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE" + +/** + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + */ +#define SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE "SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE" + /** * A variable controlling the audio category on iOS and macOS. * @@ -225,7 +282,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" @@ -238,7 +295,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_CHANNELS "SDL_AUDIO_CHANNELS" @@ -261,7 +318,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME "SDL_AUDIO_DEVICE_APP_ICON_NAME" @@ -283,7 +340,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" @@ -310,7 +367,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" @@ -336,7 +393,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" @@ -347,7 +404,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_INPUT_FILE "SDL_AUDIO_DISK_INPUT_FILE" @@ -358,7 +415,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_OUTPUT_FILE "SDL_AUDIO_DISK_OUTPUT_FILE" @@ -371,7 +428,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DISK_TIMESCALE "SDL_AUDIO_DISK_TIMESCALE" @@ -385,7 +442,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" @@ -398,7 +455,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_DUMMY_TIMESCALE "SDL_AUDIO_DUMMY_TIMESCALE" @@ -409,18 +466,23 @@ extern "C" { * device, this hint can be used to specify a default format that will be * used. * - * The variable can be set to the following values: - "U8": Unsigned 8-bit - * audio - "S8": Signed 8-bit audio - "S16LE": Signed 16-bit little-endian - * audio - "S16BE": Signed 16-bit big-endian audio - "S16": Signed 16-bit - * native-endian audio (default) - "S32LE": Signed 32-bit little-endian audio - * - "S32BE": Signed 32-bit big-endian audio - "S32": Signed 32-bit - * native-endian audio - "F32LE": Floating point little-endian audio - - * "F32BE": Floating point big-endian audio - "F32": Floating point - * native-endian audio + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FORMAT "SDL_AUDIO_FORMAT" @@ -433,7 +495,7 @@ extern "C" { * * This hint should be set before an audio device is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_FREQUENCY "SDL_AUDIO_FREQUENCY" @@ -456,7 +518,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" @@ -471,7 +533,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" @@ -486,7 +548,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" @@ -509,7 +571,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" @@ -525,7 +587,7 @@ extern "C" { * best camera backend on your behalf. This hint needs to be set before * SDL_Init() is called to be useful. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" @@ -558,7 +620,7 @@ extern "C" { * * The items can be prefixed by '+'/'-' to add/remove features. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" @@ -572,7 +634,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" @@ -601,7 +663,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" @@ -619,7 +681,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" @@ -640,7 +702,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" @@ -653,7 +715,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" @@ -668,12 +730,13 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all * - any other string without a leading # sign applies to the element on the * page with that ID. * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" @@ -690,7 +753,7 @@ extern "C" { * * This hint must be set before SDL_StartTextInput() is called * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" @@ -707,7 +770,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVDEV_DEVICES "SDL_EVDEV_DEVICES" @@ -731,7 +794,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" @@ -751,7 +814,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" @@ -772,7 +835,7 @@ extern "C" { * * This hint should be set before calling SDL_GetWindowSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" @@ -787,7 +850,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" @@ -803,7 +866,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" @@ -827,7 +890,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" @@ -845,7 +908,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" @@ -863,7 +926,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" @@ -886,7 +949,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" @@ -898,7 +961,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" @@ -910,7 +973,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" @@ -925,7 +988,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" @@ -941,7 +1004,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" @@ -952,7 +1015,7 @@ extern "C" { * * This hint should be set before calling SDL_StartTextInput() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" @@ -970,7 +1033,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB "SDL_HIDAPI_LIBUSB" @@ -988,7 +1051,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_LIBUSB_WHITELIST "SDL_HIDAPI_LIBUSB_WHITELIST" @@ -1002,7 +1065,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_UDEV "SDL_HIDAPI_UDEV" @@ -1011,12 +1074,12 @@ extern "C" { * * By default, SDL will try all available GPU backends in a reasonable order * until it finds one that can work, but this hint allows the app or user to - * force a specific target, such as "d3d11" if, say, your hardware supports - * D3D12 but want to try using D3D11 instead. + * force a specific target, such as "direct3d11" if, say, your hardware + * supports D3D12 but want to try using D3D11 instead. * - * This hint should be set before SDL_GPUSelectBackend() is called. + * This hint should be set before any GPU functions are called. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_GPU_DRIVER "SDL_GPU_DRIVER" @@ -1035,7 +1098,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" @@ -1052,7 +1115,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" @@ -1075,7 +1138,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IME_IMPLEMENTED_UI "SDL_IME_IMPLEMENTED_UI" @@ -1094,7 +1157,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" @@ -1111,7 +1174,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" @@ -1128,7 +1191,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" @@ -1149,7 +1212,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" @@ -1167,7 +1230,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" @@ -1188,7 +1251,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" @@ -1198,10 +1261,35 @@ extern "C" { * * This variable is currently only used by the Linux joystick driver. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" +/** + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_ENHANCED_REPORTS "SDL_JOYSTICK_ENHANCED_REPORTS" + /** * A variable containing a list of flightstick style controllers. * @@ -1215,7 +1303,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" @@ -1236,7 +1324,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" @@ -1246,12 +1334,14 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": GameInput is not used. (default) + * - "0": GameInput is not used. * - "1": GameInput is used. * + * The default is "1" on GDK platforms, and "0" otherwise. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMEINPUT "SDL_JOYSTICK_GAMEINPUT" @@ -1269,7 +1359,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" @@ -1290,7 +1380,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" @@ -1305,9 +1395,9 @@ extern "C" { * This variable is the default for all drivers, but can be overridden by the * hints for specific drivers below. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" @@ -1322,9 +1412,9 @@ extern "C" { * - "1": Left and right Joy-Con controllers will be combined into a single * controller. (default) * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" @@ -1339,9 +1429,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" @@ -1362,7 +1452,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" @@ -1377,9 +1467,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" @@ -1398,7 +1488,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" @@ -1413,9 +1503,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" @@ -1430,9 +1520,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" @@ -1452,9 +1542,9 @@ extern "C" { * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" @@ -1469,9 +1559,9 @@ extern "C" { * * The default value is 0. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" @@ -1486,9 +1576,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" @@ -1503,36 +1593,10 @@ extern "C" { * This hint can be set anytime, but only takes effect when extended input * reports are enabled. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL "SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL" -/** - * A variable controlling whether extended input reports should be used for - * PS4 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports are enabled. - * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value will also control - * the state of extended reports on PS5 controllers when the - * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for PS5 controllers should * be used. @@ -1544,9 +1608,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" @@ -1559,35 +1623,10 @@ extern "C" { * - "0": player LEDs are not enabled. * - "1": player LEDs are enabled. (default) * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" -/** - * A variable controlling whether extended input reports should be used for - * PS5 controllers when using the HIDAPI driver. - * - * The variable can be set to the following values: - * - * - "0": extended reports are not enabled. (default) - * - "1": extended reports. - * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break - * DirectInput handling for applications that don't use SDL. - * - * Once extended reports are enabled, they can not be disabled without power - * cycling the controller. - * - * For compatibility with applications written for versions of SDL prior to - * the introduction of PS5 controller support, this value defaults to the - * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. - * - * This hint can be enabled anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" - /** * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD * controllers should be used. @@ -1599,9 +1638,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" @@ -1616,7 +1655,7 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" @@ -1631,12 +1670,31 @@ extern "C" { * Bluetooth access and may prompt the user for permission on iOS and * Android. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" +/** + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED "SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED" + /** * A variable controlling whether the HIDAPI driver for the Steam Deck builtin * controller should be used. @@ -1648,12 +1706,23 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" +/** + * A variable controlling whether the HIDAPI driver for HORI licensed Steam + * controllers should be used. + * + * This variable can be set to the following values: "0" - HIDAPI driver is + * not used "1" - HIDAPI driver is used + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + */ +#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI" + /** * A variable controlling whether the HIDAPI driver for Nintendo Switch * controllers should be used. @@ -1665,9 +1734,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" @@ -1686,7 +1755,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" @@ -1701,7 +1770,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" @@ -1717,7 +1786,7 @@ extern "C" { * * This hint should be set before opening a Joy-Con controller. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" @@ -1730,12 +1799,12 @@ extern "C" { * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE - * for now. + * This driver doesn't work with the dolphinbar, so the default is false for + * now. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" @@ -1750,7 +1819,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" @@ -1766,9 +1835,9 @@ extern "C" { * The default is "0" on Windows, otherwise the value of * SDL_HINT_JOYSTICK_HIDAPI * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" @@ -1783,9 +1852,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" @@ -1800,7 +1869,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" @@ -1815,9 +1884,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" @@ -1832,9 +1901,9 @@ extern "C" { * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * - * This hint should be set before enumerating controllers. + * This hint should be set before initializing joysticks and gamepads. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" @@ -1853,7 +1922,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" @@ -1868,7 +1937,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" @@ -1883,7 +1952,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" @@ -1898,7 +1967,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" @@ -1916,7 +1985,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" @@ -1932,7 +2001,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" @@ -1947,7 +2016,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" @@ -1962,7 +2031,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" @@ -1979,7 +2048,7 @@ extern "C" { * * This hint should be set before a gamepad is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" @@ -1994,7 +2063,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" @@ -2004,12 +2073,12 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": A separate thread is not used. (default) - * - "1": A separate thread is used for handling raw input messages. + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" @@ -2026,7 +2095,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" @@ -2047,7 +2116,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" @@ -2062,7 +2131,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" @@ -2079,7 +2148,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" @@ -2100,7 +2169,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" @@ -2118,7 +2187,7 @@ extern "C" { * * This hint should be set before a controller is opened. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" @@ -2139,7 +2208,7 @@ extern "C" { * - "latin_letters": For keyboards using non-Latin letters, such as Russian * or Thai, the letter keys generate keycodes as though it had an en_US * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian - * keyboard would yield 'a' instead of 'ф'. + * keyboard would yield 'a' instead of a Cyrillic letter. * * The default value for this hint is "french_numbers,latin_letters" * @@ -2152,7 +2221,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS" @@ -2166,7 +2235,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" @@ -2194,7 +2263,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" @@ -2220,7 +2289,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_LOGGING "SDL_LOGGING" @@ -2234,9 +2303,9 @@ extern "C" { * (default) * - "1": The application may remain in the background when launched. * - * This hint should be set before applicationDidFinishLaunching() is called. + * This hint needs to be set before SDL_Init(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" @@ -2252,7 +2321,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" @@ -2275,25 +2344,73 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" +/** + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_OPTION_AS_ALT "SDL_MAC_OPTION_AS_ALT" + +/** + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM" + /** * Request SDL_AppIterate() be called at a specific rate. * - * This number is in Hz, so "60" means try to iterate 60 times per second. + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. * * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, * this hint is ignored. When the hint can be used, it is allowed to be * changed at any time. * - * This defaults to 60, and specifying NULL for the hint's value will restore + * This defaults to 0, and specifying NULL for the hint's value will restore * the default. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" @@ -2312,7 +2429,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" @@ -2321,7 +2438,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" @@ -2330,10 +2447,22 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" +/** + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR "SDL_MOUSE_DEFAULT_SYSTEM_CURSOR" + /** * A variable controlling whether warping a hidden mouse cursor will activate * relative mouse mode. @@ -2362,7 +2491,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE "SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE" @@ -2376,7 +2505,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" @@ -2386,7 +2515,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" @@ -2407,32 +2536,17 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" -/** - * A variable controlling whether relative mouse mode is implemented using - * mouse warping. - * - * The variable can be set to the following values: - * - * - "0": Relative mouse mode uses raw input. (default) - * - "1": Relative mouse mode uses mouse warping. - * - * This hint can be set anytime relative mode is not currently enabled. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" - /** * A variable setting the scale for mouse motion, in floating point, when the * mouse is in relative mode. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" @@ -2446,12 +2560,12 @@ extern "C" { * - "1": Relative mouse motion will be scaled using the system mouse * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after * system speed scale. * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" @@ -2470,7 +2584,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" @@ -2478,9 +2592,10 @@ extern "C" { * A variable controlling whether the hardware cursor stays visible when * relative mode is active. * - * This variable can be set to the following values: "0" - The cursor will be - * hidden while relative mode is active (default) "1" - The cursor will remain - * visible while relative mode is active + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active * * Note that for systems without raw hardware inputs, relative mode is * implemented using warping, so the hardware cursor will visibly warp between @@ -2488,27 +2603,10 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE" -/** - * Controls how often SDL issues cursor confinement commands to the operating - * system while relative mode is active, in case the desired confinement state - * became out-of-sync due to interference from other running programs. - * - * The variable can be integers representing miliseconds between each refresh. - * A value of zero means SDL will not automatically refresh the confinement. - * The default value varies depending on the operating system, this variable - * might not have any effects on inapplicable platforms such as those without - * a cursor. - * - * This hint can be set anytime. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_MOUSE_RELATIVE_CLIP_INTERVAL "SDL_MOUSE_RELATIVE_CLIP_INTERVAL" - /** * A variable controlling whether mouse events should generate synthetic touch * events. @@ -2522,7 +2620,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" @@ -2540,7 +2638,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_MUTE_CONSOLE_KEYBOARD "SDL_MUTE_CONSOLE_KEYBOARD" @@ -2555,7 +2653,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" @@ -2563,12 +2661,25 @@ extern "C" { * Specify the OpenGL library to load. * * This hint should be set before creating an OpenGL window or creating an - * OpenGL context. + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_LIBRARY "SDL_OPENGL_LIBRARY" +/** + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_EGL_LIBRARY "SDL_EGL_LIBRARY" + /** * A variable controlling what driver to use for OpenGL ES contexts. * @@ -2599,10 +2710,22 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" +/** + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_OPENVR_LIBRARY "SDL_OPENVR_LIBRARY" + /** * A variable controlling which orientations are allowed on iOS/Android. * @@ -2618,7 +2741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ORIENTATIONS "SDL_ORIENTATIONS" @@ -2638,7 +2761,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" @@ -2656,7 +2779,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" @@ -2673,9 +2796,13 @@ extern "C" { * - "1": SDL will send a quit event when the last window is requesting to * close. (default) * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" @@ -2690,7 +2817,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" @@ -2706,7 +2833,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" @@ -2720,7 +2847,7 @@ extern "C" { * * By default, SDL does not use Vulkan Validation Layers. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" @@ -2734,7 +2861,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_DEBUG "SDL_RENDER_GPU_DEBUG" @@ -2749,7 +2876,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_GPU_LOW_POWER "SDL_RENDER_GPU_LOW_POWER" @@ -2758,7 +2885,7 @@ extern "C" { * * If the application doesn't pick a specific renderer to use, this variable * specifies the name of the preferred renderer. If the preferred renderer - * can't be initialized, the normal default renderer is used. + * can't be initialized, creating a renderer will fail. * * This variable is case insensitive and can be set to the following values: * @@ -2770,14 +2897,19 @@ extern "C" { * - "opengles" * - "metal" * - "vulkan" + * - "gpu" * - "software" * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * * The default varies by platform, but it's the first one in the list that is * available on the current platform. * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" @@ -2795,7 +2927,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" @@ -2810,7 +2942,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" @@ -2827,7 +2959,7 @@ extern "C" { * * This hint should be set before creating a renderer. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" @@ -2844,7 +2976,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" @@ -2861,7 +2993,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. * * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED */ @@ -2883,7 +3015,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" @@ -2895,7 +3027,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" @@ -2917,7 +3049,7 @@ extern "C" { * * This hint should be set before calling SDL_DisableScreenSaver() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" @@ -2936,7 +3068,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" @@ -2950,7 +3082,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" @@ -2964,7 +3096,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" @@ -2991,32 +3123,32 @@ extern "C" { * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling * policy * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** * A string specifying additional information to use with - * SDL_SetThreadPriority. + * SDL_SetCurrentThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in - * order to apply a thread priority. For example on systems using pthreads the - * scheduler policy is changed automatically to a policy that works well with - * a given priority. Code which has specific requirements can override SDL's - * default behavior with this hint. + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. * * pthread hint values are "current", "other", "fifo" and "rr". Currently no * other platform hint values are defined but may be in the future. * * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the * distro configured execution budget for rtkit. This budget can be queried - * through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). * - * This hint should be set before calling SDL_SetThreadPriority() + * This hint should be set before calling SDL_SetCurrentThreadPriority() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" @@ -3036,7 +3168,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" @@ -3051,7 +3183,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" @@ -3072,7 +3204,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -3087,7 +3219,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" @@ -3101,10 +3233,35 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" +/** + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_DISPLAY_PRIORITY "SDL_VIDEO_DISPLAY_PRIORITY" + /** * Tell the video driver that we only want a double buffer. * @@ -3124,7 +3281,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" @@ -3136,9 +3293,13 @@ extern "C" { * force a specific target, such as "x11" if, say, you are on Wayland but want * to try talking to the X server instead. * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" @@ -3151,7 +3312,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES "SDL_VIDEO_DUMMY_SAVE_FRAMES" @@ -3165,7 +3326,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK" @@ -3181,7 +3342,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" @@ -3199,10 +3360,31 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" +/** + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY "SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY" + /** * A variable controlling whether fullscreen windows are minimized when they * lose focus. @@ -3215,7 +3397,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" @@ -3232,7 +3414,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES "SDL_VIDEO_OFFSCREEN_SAVE_FRAMES" @@ -3258,7 +3440,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" @@ -3276,7 +3458,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" @@ -3296,7 +3478,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" @@ -3318,7 +3500,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" @@ -3338,7 +3520,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" @@ -3357,6 +3539,8 @@ extern "C" { * * - Rounding errors can result with odd window sizes and/or desktop scales, * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. * - The window may be unusably small on scaled desktops. * - The window may jump in size when moving between displays of different * scale factors. @@ -3375,7 +3559,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" @@ -3397,7 +3581,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" @@ -3412,7 +3596,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" @@ -3431,7 +3615,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" @@ -3445,7 +3629,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_NODIRECTCOLOR "SDL_VIDEO_X11_NODIRECTCOLOR" @@ -3456,7 +3640,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" @@ -3465,7 +3649,7 @@ extern "C" { * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_VISUALID "SDL_VIDEO_X11_VISUALID" @@ -3474,7 +3658,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" @@ -3488,7 +3672,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" @@ -3503,7 +3687,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_BACK_TOUCH "SDL_VITA_ENABLE_BACK_TOUCH" @@ -3518,7 +3702,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_ENABLE_FRONT_TOUCH "SDL_VITA_ENABLE_FRONT_TOUCH" @@ -3529,7 +3713,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_MODULE_PATH "SDL_VITA_MODULE_PATH" @@ -3542,7 +3726,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_INIT "SDL_VITA_PVR_INIT" @@ -3557,7 +3741,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_RESOLUTION "SDL_VITA_RESOLUTION" @@ -3572,7 +3756,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_PVR_OPENGL "SDL_VITA_PVR_OPENGL" @@ -3588,7 +3772,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" @@ -3599,7 +3783,7 @@ extern "C" { * * This hint should be set before calling SDL_Vulkan_CreateSurface() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_DISPLAY "SDL_VULKAN_DISPLAY" @@ -3609,7 +3793,7 @@ extern "C" { * This hint should be set before creating a Vulkan window or calling * SDL_Vulkan_LoadLibrary(). * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_VULKAN_LIBRARY "SDL_VULKAN_LIBRARY" @@ -3641,7 +3825,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" @@ -3653,7 +3837,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_CHUNK_LIMIT "SDL_WAVE_CHUNK_LIMIT" @@ -3681,7 +3865,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" @@ -3701,7 +3885,7 @@ extern "C" { * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" @@ -3718,7 +3902,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" @@ -3735,7 +3919,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" @@ -3753,7 +3937,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" @@ -3769,7 +3953,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" @@ -3785,7 +3969,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" @@ -3814,7 +3998,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" @@ -3829,7 +4013,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" @@ -3845,7 +4029,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_GAMEINPUT "SDL_WINDOWS_GAMEINPUT" @@ -3859,7 +4043,7 @@ extern "C" { * * This hint can be set anytime. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" @@ -3880,7 +4064,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" @@ -3890,9 +4074,18 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** @@ -3917,7 +4110,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" @@ -3934,123 +4127,10 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE "SDL_WINDOWS_ERASE_BACKGROUND_MODE" -/** - * A variable controlling whether back-button-press events on Windows Phone to - * be marked as handled. - * - * Windows Phone devices typically feature a Back button. When pressed, the OS - * will emit back-button-press events, which apps are expected to handle in an - * appropriate manner. If apps do not explicitly mark these events as - * 'Handled', then the OS will invoke its default behavior for unhandled - * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate - * the app (and attempt to switch to the previous app, or to the device's home - * screen). - * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to - * mark back-button-press events as Handled, if and when one is sent to the - * app. - * - * Internally, Windows Phone sends back button events as parameters to special - * back-button-press callback functions. Apps that need to respond to - * back-button-press events are expected to register one or more callback - * functions for such, shortly after being launched (during the app's - * initialization phase). After the back button is pressed, the OS will invoke - * these callbacks. If the app's callback(s) do not explicitly mark the event - * as handled by the time they return, or if the app never registers one of - * these callback, the OS will consider the event un-handled, and it will - * apply its default back button behavior (terminate the app). - * - * SDL registers its own back-button-press callback with the Windows Phone OS. - * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN - * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after - * which it will check the contents of the hint, - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the - * back button event's Handled property will get set to 'true'. If the hint's - * value is set to something else, or if it is unset, SDL will leave the - * event's Handled property alone. (By default, the OS sets this property to - * 'false', to note.) - * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a - * back button is pressed, or can set it in direct-response to a back button - * being pressed. - * - * In order to get notified when a back button is pressed, SDL apps should - * register a callback function with SDL_AddEventWatch(), and have it listen - * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. - * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for - * either event type is suitable.) Any value of - * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied - * to the OS' current back-button-press event. - * - * More details on back button behavior in Windows Phone apps can be found at - * the following page, on Microsoft's developer site: - * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" - -/** - * A variable specifying the label text for a WinRT app's privacy policy link. - * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, - * 8.1, and RT, Microsoft mandates that this policy be available via the - * Windows Settings charm. SDL provides code to add a link there, with its - * label text being set via the optional hint, - * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that a privacy policy's contents are not set via this hint. A - * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the - * actual text of the policy. - * - * The contents of this hint should be encoded as a UTF8 string. - * - * The default value is "Privacy Policy". - * - * For additional information on linking to a privacy policy, see the - * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. - * - * This hint should be set before SDL is initialized. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" - -/** - * A variable specifying the URL to a WinRT app's privacy policy. - * - * All network-enabled WinRT apps must make a privacy policy available to its - * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be - * available in the Windows Settings charm, as accessed from within the app. - * SDL provides code to add a URL-based link there, which can point to the - * app's privacy policy. - * - * To setup a URL to an app's privacy policy, set - * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. - * The contents of the hint should be a valid URL. For example, - * "http://www.example.com". - * - * The default value is "", which will prevent SDL from adding a privacy - * policy link to the Settings charm. This hint should only be set during app - * init. - * - * The label text of an app's "Privacy Policy" link may be customized via - * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. - * - * Please note that on Windows Phone, Microsoft does not provide standard UI - * for displaying a privacy policy link, and as such, - * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. - * Network-enabled phone apps should display their privacy policy through some - * other, in-app means. - * - * \since This hint is available since SDL 3.0.0. - */ -#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" - /** * A variable controlling whether X11 windows are marked as override-redirect. * @@ -4068,7 +4148,7 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" @@ -4085,18 +4165,18 @@ extern "C" { * * This hint should be set before creating a window. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** * Specify the XCB library to load for the X11 driver. * - * This defaults to "libX11-xcb.so" + * The default is platform-specific, often "libX11-xcb.so.1". * * This hint should be set before initializing the video subsystem. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_X11_XCB_LIBRARY "SDL_X11_XCB_LIBRARY" @@ -4111,7 +4191,7 @@ extern "C" { * * This hint should be set before SDL is initialized. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" @@ -4135,15 +4215,45 @@ extern "C" { * This hint should be set before an assertion failure is triggered and can be * changed at any time. * - * \since This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.2.0. */ #define SDL_HINT_ASSERT "SDL_ASSERT" +/** + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_MOUSE_EVENTS "SDL_PEN_MOUSE_EVENTS" + +/** + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + */ +#define SDL_HINT_PEN_TOUCH_EVENTS "SDL_PEN_TOUCH_EVENTS" + /** * An enumeration of hint priorities. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_HintPriority { @@ -4162,18 +4272,18 @@ typedef enum SDL_HintPriority * \param name the hint to set. * \param value the value of the hint variable. * \param priority the SDL_HintPriority level for the hint. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHintWithPriority(const char *name, const char *value, SDL_HintPriority priority); /** * Set a hint with normal priority. @@ -4184,18 +4294,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, c * * \param name the hint to set. * \param value the value of the hint variable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_ResetHint * \sa SDL_SetHintWithPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetHint(const char *name, const char *value); /** * Reset a hint to the default value. @@ -4205,17 +4315,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, const char *v * change. * * \param name the hint to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_ResetHints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ResetHint(const char *name); /** * Reset all hints to the default values. @@ -4226,7 +4336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetHint */ @@ -4245,7 +4355,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); * callback instead is always thread-safe, as SDL holds a lock * on the thread subsystem during the callback. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetHint * \sa SDL_SetHintWithPriority @@ -4262,12 +4372,12 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetHint(const char *name); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetHint * \sa SDL_SetHint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetHintBoolean(const char *name, bool default_value); /** * A callback used to send notifications of hint value changes. @@ -4284,7 +4394,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bo * hint value. SDL holds a lock on the hint subsystem when * calling this callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ @@ -4300,16 +4410,16 @@ typedef void(SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const * \param callback An SDL_HintCallback function that will be called when the * hint value changes. * \param userdata a pointer to pass to the callback function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveHintCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_AddHintCallback(const char *name, SDL_HintCallback callback, void *userdata); /** * Remove a function watching a particular hint. @@ -4321,7 +4431,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddHintCallback(const char *name, SDL_H * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddHintCallback */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h index 5a13947..adf0de8 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_init.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,10 +22,30 @@ /** * # CategoryInit * - * SDL subsystem init and quit functions. + * All SDL programs need to initialize the library before starting to work + * with it. + * + * Almost everything can simply call SDL_Init() near startup, with a handful + * of flags to specify subsystems to touch. These are here to make sure SDL + * does not even attempt to touch low-level pieces of the operating system + * that you don't intend to use. For example, you might be using SDL for video + * and input but chose an external library for audio, and in this case you + * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that + * external library has complete control. + * + * Most apps, when terminating, should call SDL_Quit(). This will clean up + * (nearly) everything that SDL might have allocated, and crucially, it'll + * make sure that the display's resolution is back to what the user expects if + * you had previously changed it for your game. + * + * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup + * to fill in details about the program. This is completely optional, but it + * helps in small ways (we can provide an About dialog box for the macOS menu, + * we can name the app in the system's audio mixer, etc). Those that want to + * provide a _lot_ of information should look at the more-detailed + * SDL_SetAppMetadataProperty(). */ - #ifndef SDL_init_h_ #define SDL_init_h_ @@ -47,7 +67,7 @@ extern "C" { * These are the flags which may be passed to SDL_Init(). You should specify * the subsystems which you will be using in your application. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -57,9 +77,8 @@ extern "C" { */ typedef Uint32 SDL_InitFlags; -#define SDL_INIT_TIMER 0x00000001u #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ -#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` */ +#define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */ #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD */ #define SDL_INIT_HAPTIC 0x00001000u #define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */ @@ -85,7 +104,7 @@ typedef Uint32 SDL_InitFlags; * [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. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_AppResult { @@ -94,10 +113,70 @@ typedef enum SDL_AppResult SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ } SDL_AppResult; +/** + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); + +/** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ 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); + +/** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); + +/** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. @@ -117,11 +196,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * * `flags` may be any of the following OR'd together: * - * - `SDL_INIT_TIMER`: timer subsystem * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem + * subsystem, should be initialized on the main thread. * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem @@ -143,10 +221,10 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * SDL_SetAppMetadataProperty(). * * \param flags subsystem initialization flags. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty @@ -155,7 +233,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate); * \sa SDL_SetMainReady * \sa SDL_WasInit */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Init(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); /** * Compatibility function to initialize the SDL library. @@ -163,16 +241,16 @@ extern SDL_DECLSPEC SDL_bool 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit * \sa SDL_QuitSubSystem */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); +extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); /** * Shut down specific SDL subsystems. @@ -182,7 +260,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem * \sa SDL_Quit @@ -196,7 +274,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_InitSubSystem @@ -214,13 +292,70 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); * application is shutdown, but it is not wise to do this from a library or * other dynamically loaded code. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_QuitSubSystem */ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void); +/** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void); + +/** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + */ +typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata); + +/** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete); + /** * Specify basic metadata about your app. * @@ -248,16 +383,16 @@ 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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadataProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); +extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); /** * Specify metadata about your app through a set of properties. @@ -274,7 +409,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * Multiple calls to this function are allowed, but various state might not * change once it has been set up with a previous call to this function. * - * Once set, this metadata can be read using SDL_GetMetadataProperty(). + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). * * These are the supported properties: * @@ -310,17 +445,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, con * * \param name the name of the metadata property to set. * \param value the value of the property, or NULL to remove that property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value); +extern SDL_DECLSPEC 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" @@ -346,7 +481,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name * freed if you call SDL_SetAppMetadataProperty() to set that * property from another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h index efba11d..bac6d7a 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_intrin.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -19,8 +19,31 @@ 3. This notice may not be removed or altered from any source distribution. */ -/* - * Header file for CPU intrinsics for SDL +/* WIKI CATEGORY: Intrinsics */ + +/** + * # CategoryIntrinsics + * + * SDL does some preprocessor gymnastics to determine if any CPU-specific + * compiler intrinsics are available, as this is not necessarily an easy thing + * to calculate, and sometimes depends on quirks of a system, versions of + * build tools, and other external forces. + * + * Apps including SDL's headers will be able to check consistent preprocessor + * definitions to decide if it's safe to use compiler intrinsics for a + * specific CPU architecture. This check only tells you that the compiler is + * capable of using those intrinsics; at runtime, you should still check if + * they are available on the current system with the + * [CPU info functions](https://wiki.libsdl.org/SDL3/CategoryCPUInfo) + * , such as SDL_HasSSE() or SDL_HasNEON(). Otherwise, the process might crash + * for using an unsupported CPU instruction. + * + * SDL only sets preprocessor defines for CPU intrinsics if they are + * supported, so apps should check with `#ifdef` and not `#if`. + * + * SDL will also include the appropriate instruction-set-specific support + * headers, so if SDL decides to define SDL_SSE2_INTRINSICS, it will also + * `#include ` as well. */ #ifndef SDL_intrin_h_ @@ -28,6 +51,169 @@ #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LSX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Loongarch LSX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_LASX_INTRINSICS + */ +#define SDL_LASX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports ARM NEON intrinsics. + * + * If this macro is defined, SDL will have already included `` + * ``, ``, and ``, as appropriate. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_NEON_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports PowerPC Altivec intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ALTIVEC_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel MMX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + */ +#define SDL_MMX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE3 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE3_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.1 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_2_INTRINSICS + */ +#define SDL_SSE4_1_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel SSE4.2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SSE_INTRINSICS + * \sa SDL_SSE2_INTRINSICS + * \sa SDL_SSE3_INTRINSICS + * \sa SDL_SSE4_1_INTRINSICS + */ +#define SDL_SSE4_2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX2_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX2 intrinsics. + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX512F_INTRINSICS + */ +#define SDL_AVX2_INTRINSICS 1 + +/** + * Defined if (and only if) the compiler supports Intel AVX-512F intrinsics. + * + * AVX-512F is also sometimes referred to as "AVX-512 Foundation." + * + * If this macro is defined, SDL will have already included `` + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AVX_INTRINSICS + * \sa SDL_AVX2_INTRINSICS + */ +#define SDL_AVX512F_INTRINSICS 1 +#endif + /* Need to do this here because intrin.h has C++ code in it */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) @@ -81,7 +267,21 @@ _m_prefetch(void *__P) #endif #endif /* compiler version */ -#if defined(__clang__) && defined(__has_attribute) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro to decide if the compiler supports `__attribute__((target))`. + * + * Even though this is defined in SDL's public headers, it is generally not + * used directly by apps. Apps should probably just use SDL_TARGETING + * directly, instead. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) # if __has_attribute(target) # define SDL_HAS_TARGET_ATTRIBS # endif @@ -91,7 +291,55 @@ _m_prefetch(void *__P) # define SDL_HAS_TARGET_ATTRIBS #endif -#ifdef SDL_HAS_TARGET_ATTRIBS + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a function as targeting a specific CPU architecture. + * + * This is a hint to the compiler that a function should be built with support + * for a CPU instruction set that might be different than the rest of the + * program. + * + * The particulars of this are explained in the GCC documentation: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute + * + * An example of using this feature is to turn on SSE2 support for a specific + * function, even if the rest of the source code is not compiled to use SSE2 + * code: + * + * ```c + * #ifdef SDL_SSE2_INTRINSICS + * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) { + * ...use SSE2 intrinsic functions, etc... + * } + * #endif + * + * // later... + * #ifdef SDL_SSE2_INTRINSICS + * if (SDL_HasSSE2()) { + * DoSomethingWithSSE2(str); + * } + * #endif + * ``` + * + * The application is, on a whole, built without SSE2 instructions, so it will + * run on Intel machines that don't support SSE2. But then at runtime, it + * checks if the system supports the instructions, and then calls into a + * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't + * used on platforms that don't have SSE2 at all. + * + * On compilers without target support, this is defined to nothing. + * + * This symbol is used by SDL internally, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_TARGETING(x) __attribute__((target(x))) + +#elif defined(SDL_HAS_TARGET_ATTRIBS) # define SDL_TARGETING(x) __attribute__((target(x))) #else # define SDL_TARGETING(x) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h index a306deb..4ca1609 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_iostream.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,7 @@ * # CategoryIOStream * * SDL provides an abstract interface for reading and writing data streams. It - * offers implementations for files, memory, etc, and the app can provideo + * offers implementations for files, memory, etc, and the app can provide * their own implementations, too. * * SDL_IOStream is not related to the standard C++ iostream class, other than @@ -48,7 +48,7 @@ extern "C" { /** * SDL_IOStream status, set by a read or write operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOStatus { @@ -66,13 +66,13 @@ typedef enum SDL_IOStatus * These map to the same "whence" concept that `fseek` or `lseek` use in the * standard C runtime. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_IOWhence { SDL_IO_SEEK_SET, /**< Seek from the beginning of data */ SDL_IO_SEEK_CUR, /**< Seek relative to current read point */ - SDL_IO_SEEK_END, /**< Seek relative to the end of data */ + SDL_IO_SEEK_END /**< Seek relative to the end of data */ } SDL_IOWhence; /** @@ -83,10 +83,17 @@ typedef enum SDL_IOWhence * already offers several common types of I/O streams, via functions like * SDL_IOFromFile() and SDL_IOFromMem(). * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_IOStreamInterface { + /* The version of this interface */ + Uint32 version; + /** * Return the number of bytes in this SDL_IOStream * @@ -126,18 +133,41 @@ typedef struct SDL_IOStreamInterface */ size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status); + /** + * If the stream is buffering, make sure the data is written out. + * + * On failure, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a successful flush. + * + * \return true if successful or false on write error when flushing data. + */ + bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status); + /** * Close and free any allocated resources. * - * The SDL_IOStream is still destroyed even if this fails, so clean up anything - * even if flushing to disk returns an error. + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. * - * \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data. + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); } SDL_IOStreamInterface; +/* Check the size of SDL_IOStreamInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) || + (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56)); /** * The read/write operation structure. @@ -147,7 +177,7 @@ typedef struct SDL_IOStreamInterface * SDL_OpenIO() to provide their own stream implementation behind this * struct's abstract interface. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_IOStream SDL_IOStream; @@ -217,6 +247,8 @@ typedef struct SDL_IOStream SDL_IOStream; * than your app, trying to use this pointer will almost certainly result in * a crash! This is mostly a problem on Windows; make sure you build SDL and * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access * the filesystem. If SDL used some other method to access the filesystem, @@ -228,9 +260,12 @@ typedef struct SDL_IOStream SDL_IOStream; * \returns a pointer to the SDL_IOStream structure that is created or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -240,6 +275,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle" #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file" +#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor" #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset" /** @@ -257,15 +293,25 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of * memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromConstMem * \sa SDL_CloseIO + * \sa SDL_FlushIO * \sa SDL_ReadIO * \sa SDL_SeekIO * \sa SDL_TellIO @@ -273,6 +319,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons */ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size); +#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base" +#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size" + /** * Use this function to prepare a read-only memory buffer for use with * SDL_IOStream. @@ -290,12 +339,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size) * If you need to write to a memory buffer, you should use SDL_IOFromMem() * with a writable buffer of memory instead. * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream. * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOFromMem * \sa SDL_CloseIO @@ -323,7 +381,9 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO * \sa SDL_ReadIO @@ -347,20 +407,21 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void); * read/write a common data source, you should use the built-in * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. * - * You must free the returned pointer with SDL_CloseIO(). - * * This function makes a copy of `iface` and the caller does not need to keep - * this data around after this call. + * it around after this call. * - * \param iface the function pointers that implement this SDL_IOStream. - * \param userdata the app-controlled pointer that is passed to iface's - * functions when called. + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a pointer to the allocated memory on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE * \sa SDL_IOFromConstMem * \sa SDL_IOFromFile * \sa SDL_IOFromMem @@ -372,21 +433,32 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterfac * * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any * resources used by the stream and frees the SDL_IOStream itself. This - * returns SDL_TRUE on success, or SDL_FALSE if the stream failed to flush to - * its output (e.g. to disk). + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). * - * Note that if this fails to flush the stream to disk, this function reports - * an error, but the SDL_IOStream is still invalid once this function returns. + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. * * \param context SDL_IOStream structure to close. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenIO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context); /** * Get the properties associated with an SDL_IOStream. @@ -395,7 +467,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseIO(SDL_IOStream *context); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context); @@ -413,10 +487,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *c * \param context the SDL_IOStream to query. * \returns an SDL_IOStatus enum with the current state. * - * \threadsafety This function should not be called at the same time that - * another thread is operating on the same SDL_IOStream. + * \threadsafety This function is not thread safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); @@ -428,7 +501,9 @@ extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context); * negative error code on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); @@ -450,10 +525,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context); * negative. * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, * `SDL_IO_SEEK_END`. - * \returns the final offset in the data stream after the seek or a negative - * error code on failure; call SDL_GetError() for more information. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_TellIO */ @@ -471,7 +548,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offs * \returns the current offset in the stream, or -1 if the information can not * be determined. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SeekIO */ @@ -481,10 +560,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * Read from a data source. * * This function reads up `size` bytes from the data source to the area - * pointed at by `ptr`. This function may read less bytes than requested. It - * will return zero when the data stream is completely read, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and - * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR. + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. * * \param context a pointer to an SDL_IOStream structure. * \param ptr a pointer to a buffer to read data into. @@ -492,7 +573,9 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context); * \returns the number of bytes read, or 0 on end of file or other failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WriteIO * \sa SDL_GetIOStatus @@ -519,11 +602,14 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, * \returns the number of bytes written, which will be less than `size` on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_ReadIO * \sa SDL_SeekIO + * \sa SDL_FlushIO * \sa SDL_GetIOStatus */ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size); @@ -540,7 +626,9 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOvprintf * \sa SDL_WriteIO @@ -558,13 +646,35 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT * \returns the number of bytes written or 0 on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_IOprintf * \sa SDL_WriteIO */ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); +/** + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context); + /** * Load all the data from an SDL data stream. * @@ -575,17 +685,21 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN * The data should be freed with SDL_free(). * * \param src the SDL_IOStream to read all available data from. - * \param datasize if not NULL, will store the number of bytes read. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, SDL_bool closeio); +extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio); /** * Load all the data from a file path. @@ -601,12 +715,55 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da * \returns the data or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile */ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize); +/** + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio); + +/** + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be NULL or a + * invalid pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize); + /** * \name Read endian functions * @@ -617,26 +774,63 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasi /** * Use this function to read a byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure or EOF; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value); /** * Use this function to read a signed byte from an SDL_IOStream. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the SDL_IOStream to read from. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); + +/** + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of little-endian data from an @@ -645,30 +839,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value) * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * - * \param src the stream from which to read data. - * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value); - -/** - * Use this function to read 16 bits of little-endian data from an - * SDL_IOStream and return in native format. - * - * SDL byteswaps the data only if necessary, so the data returned will be in - * the native byte order. + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -677,14 +862,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value); /** * Use this function to read 16 bits of big-endian data from an SDL_IOStream @@ -693,14 +885,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -709,14 +908,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of little-endian data from an @@ -725,14 +931,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -741,14 +954,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value); /** * Use this function to read 32 bits of big-endian data from an SDL_IOStream @@ -757,14 +977,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -773,14 +1000,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of little-endian data from an @@ -789,14 +1023,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -805,14 +1046,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value); /** * Use this function to read 64 bits of big-endian data from an SDL_IOStream @@ -821,14 +1069,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va * SDL byteswaps the data only if necessary, so the data returned will be in * the native byte order. * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * * \param src the stream from which to read data. * \param value a pointer filled in with the data read. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value); /* @} *//* Read endian functions */ /** @@ -843,24 +1098,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value); /** * Use this function to write a signed byte to an SDL_IOStream. * * \param dst the SDL_IOStream to write to. * \param value the byte value to write. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -872,12 +1131,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value) * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -889,12 +1150,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -905,12 +1168,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value); /** * Use this function to write 16 bits in native format to an SDL_IOStream as @@ -921,12 +1186,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -938,12 +1205,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -955,12 +1224,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -971,12 +1242,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value); /** * Use this function to write 32 bits in native format to an SDL_IOStream as @@ -987,12 +1260,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1004,12 +1279,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1021,12 +1298,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1037,12 +1316,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value); /** * Use this function to write 64 bits in native format to an SDL_IOStream as @@ -1053,12 +1334,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va * * \param dst the stream to which data will be written. * \param value the data to be written, in native format. - * \returns SDL_TRUE on successful write or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value); /* @} *//* Write endian functions */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h index 43bc1e9..d15668b 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_joystick.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,8 +25,8 @@ * SDL joystick support. * * This is the lower-level joystick handling. If you want the simpler option, - * where what buttons does what is well-defined, you should use the gamepad - * API instead. + * where what each button does is well-defined, you should use the gamepad API + * instead. * * The term "instance_id" is the current instantiation of a joystick device in * the system, if the joystick is removed and then re-inserted then it will @@ -81,7 +81,7 @@ extern SDL_Mutex *SDL_joystick_lock; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Joystick SDL_Joystick; @@ -93,7 +93,7 @@ typedef struct SDL_Joystick SDL_Joystick; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_JoystickID; @@ -107,7 +107,7 @@ typedef Uint32 SDL_JoystickID; * This is by no means a complete list of everything that can be plugged into * a computer. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickType { @@ -120,7 +120,8 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_GUITAR, SDL_JOYSTICK_TYPE_DRUM_KIT, SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE + SDL_JOYSTICK_TYPE_THROTTLE, + SDL_JOYSTICK_TYPE_COUNT } SDL_JoystickType; /** @@ -129,7 +130,7 @@ typedef enum SDL_JoystickType * This is used by SDL_GetJoystickConnectionState to report how a device is * connected to the system. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_JoystickConnectionState { @@ -142,7 +143,7 @@ typedef enum SDL_JoystickConnectionState /** * The largest value an SDL_Joystick's axis can report. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MIN */ @@ -153,19 +154,13 @@ typedef enum SDL_JoystickConnectionState * * This is a negative number! * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_JOYSTICK_AXIS_MAX */ #define SDL_JOYSTICK_AXIS_MIN -32768 -/* Set max recognized G-force from accelerometer - See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed - */ -#define SDL_IPHONE_MAX_GFORCE 5.0 - - /* Function prototypes */ /** @@ -175,27 +170,27 @@ typedef enum SDL_JoystickConnectionState * joysticks while processing to guarantee that the joystick list won't change * and joystick and gamepad events will not be delivered. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); /** * Unlocking for atomic access to the joystick API. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); /** * Return whether a joystick is currently connected. * - * \returns SDL_TRUE if a joystick is connected, SDL_FALSE otherwise. + * \returns true if a joystick is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoysticks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. @@ -206,7 +201,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasJoystick * \sa SDL_OpenJoystick @@ -222,7 +217,7 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickName * \sa SDL_GetJoysticks @@ -238,7 +233,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPath * \sa SDL_GetJoysticks @@ -253,7 +248,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID * \param instance_id the joystick instance ID. * \returns the player index of a joystick, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoysticks @@ -269,7 +264,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID i * \returns the GUID of the selected joystick. If called with an invalid * instance_id, this function returns a zero GUID. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUID * \sa SDL_GUIDToString @@ -286,7 +281,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID ins * \returns the USB vendor ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendor * \sa SDL_GetJoysticks @@ -303,7 +298,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID ins * \returns the USB product ID of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProduct * \sa SDL_GetJoysticks @@ -320,7 +315,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID in * \returns the product version of the selected joystick. If called with an * invalid instance_id, this function returns 0. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersion * \sa SDL_GetJoysticks @@ -337,7 +332,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_Joysti * invalid instance_id, this function returns * `SDL_JOYSTICK_TYPE_UNKNOWN`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickType * \sa SDL_GetJoysticks @@ -354,7 +349,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti * \returns a joystick identifier or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseJoystick */ @@ -367,7 +362,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID insta * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * opened yet; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); @@ -378,7 +373,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex * \sa SDL_SetJoystickPlayerIndex @@ -388,7 +383,7 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int pl /** * The structure that describes a virtual joystick touchpad. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -401,7 +396,7 @@ typedef struct SDL_VirtualJoystickTouchpadDesc /** * The structure that describes a virtual joystick sensor. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_VirtualJoystickDesc */ @@ -414,16 +409,19 @@ typedef struct SDL_VirtualJoystickSensorDesc /** * The structure that describes a virtual joystick. * - * All elements of this structure are optional and can be left 0. + * This structure should be initialized using SDL_INIT_INTERFACE(). All + * elements of this structure are optional. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick + * \sa SDL_INIT_INTERFACE * \sa SDL_VirtualJoystickSensorDesc * \sa SDL_VirtualJoystickTouchpadDesc */ typedef struct SDL_VirtualJoystickDesc { + Uint32 version; /**< the version of this interface */ Uint16 type; /**< `SDL_JoystickType` */ Uint16 padding; /**< unused */ Uint16 vendor_id; /**< the USB vendor ID of this joystick */ @@ -446,22 +444,32 @@ typedef struct SDL_VirtualJoystickDesc void *userdata; /**< User data pointer passed to callbacks */ void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - SDL_bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - SDL_bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - SDL_bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - SDL_bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - SDL_bool (SDLCALL *SetSensorsEnabled)(void *userdata, SDL_bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ + bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ + bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ + bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ + bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ + bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ } SDL_VirtualJoystickDesc; +/* Check the size of SDL_VirtualJoystickDesc + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || + (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); + /** * Attach a new virtual joystick. * - * \param desc joystick description. + * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DetachVirtualJoystick */ @@ -472,24 +480,24 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V * * \param instance_id the joystick instance ID, previously returned from * SDL_AttachVirtualJoystick(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AttachVirtualJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); /** * Query whether or not a joystick is virtual. * * \param instance_id the joystick instance ID. - * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise. + * \returns true if the joystick is virtual, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); +extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); /** * Set the state of an axis on an opened virtual joystick. @@ -507,12 +515,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instan * \param joystick the virtual joystick on which to set state. * \param axis the index of the axis on the virtual joystick to update. * \param value the new value for the specified axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); /** * Generate ball motion on an opened virtual joystick. @@ -527,12 +535,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *jo * \param ball the index of the ball on the virtual joystick to update. * \param xrel the relative motion on the X axis. * \param yrel the relative motion on the Y axis. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); /** * Set the state of a button on an opened virtual joystick. @@ -545,13 +553,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *jo * * \param joystick the virtual joystick on which to set state. * \param button the index of the button on the virtual joystick to update. - * \param value the new value for the specified button. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param down true if the button is pressed, false otherwise. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); /** * Set the state of a hat on an opened virtual joystick. @@ -565,12 +573,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick * * \param joystick the virtual joystick on which to set state. * \param hat the index of the hat on the virtual joystick to update. * \param value the new value for the specified hat. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); /** * Set touchpad finger state on an opened virtual joystick. @@ -585,19 +593,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joy * \param touchpad the index of the touchpad on the virtual joystick to * update. * \param finger the index of the finger on the touchpad to set. - * \param state `SDL_PRESSED` if the finger is pressed, `SDL_RELEASED` if the - * finger is released. + * \param down true if the finger is pressed, false if the finger is released. * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, * with the origin in the upper left. * \param pressure the pressure of the finger. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); /** * Send a sensor update for an opened virtual joystick. @@ -614,12 +621,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick * the sensor reading. * \param data the data associated with the sensor reading. * \param num_values the number of values pointed to by `data`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); /** * Get the properties associated with a joystick. @@ -641,7 +648,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joyst * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); @@ -658,7 +665,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickNameForID */ @@ -671,7 +678,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPathForID */ @@ -686,7 +693,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joyst * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the player index, or -1 if it's not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickPlayerIndex */ @@ -698,14 +705,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param player_index player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickPlayerIndex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); /** * Get the implementation-dependent GUID for the joystick. @@ -717,7 +724,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *jo * this function returns a zero GUID; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID * \sa SDL_GUIDToString @@ -732,7 +739,7 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickVendorForID */ @@ -746,7 +753,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick) * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductForID */ @@ -760,7 +767,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the product version of the selected joystick, or 0 if unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickProductVersionForID */ @@ -775,7 +782,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j * \returns the firmware version of the selected joystick, or 0 if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); @@ -788,7 +795,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick * * \returns the serial number of the selected joystick, or NULL if * unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); @@ -798,7 +805,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the SDL_JoystickType of the selected joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickTypeForID */ @@ -817,7 +824,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j * \param crc16 a pointer filled in with a CRC used to distinguish different * products with the same VID/PID, or 0 if not available. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickGUIDForID */ @@ -827,12 +834,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 * * Get the status of a specified joystick. * * \param joystick the joystick to query. - * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; - * call SDL_GetError() for more information. + * \returns true if the joystick has been opened, false if it has not; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); /** * Get the instance ID of an opened joystick. @@ -841,7 +848,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystic * \returns the instance ID of the specified joystick on success or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); @@ -856,7 +863,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst * \returns the number of axis controls/number of axes on success or -1 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickAxis * \sa SDL_GetNumJoystickBalls @@ -877,7 +884,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); * \returns the number of trackballs on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickBall * \sa SDL_GetNumJoystickAxes @@ -893,7 +900,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); * \returns the number of POV hats on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickHat * \sa SDL_GetNumJoystickAxes @@ -909,7 +916,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); * \returns the number of buttons on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetJoystickButton * \sa SDL_GetNumJoystickAxes @@ -927,12 +934,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick * * \param enabled whether to process joystick events or not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_JoystickEventsEnabled * \sa SDL_UpdateJoysticks */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); /** * Query the state of joystick event processing. @@ -941,14 +948,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled); * yourself and check the state of the joystick when you want joystick * information. * - * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE - * otherwise. + * \returns true if joystick events are being processed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetJoystickEventsEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); /** * Update the current state of the open joysticks. @@ -956,7 +962,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_JoystickEventsEnabled(void); * This is called automatically by the event loop if any joystick events are * enabled. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); @@ -978,7 +984,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); * \returns a 16-bit signed integer representing the current position of the * axis or 0 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickAxes */ @@ -994,11 +1000,11 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i * \param joystick an SDL_Joystick structure containing joystick information. * \param axis the axis to query; the axis indices start at index 0. * \param state upon return, the initial value is supplied here. - * \returns SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. + * \returns true if this axis has any initial value, or false if not. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); /** * Get the ball axis change since the last poll. @@ -1012,14 +1018,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystic * \param ball the ball index to query; ball indices start at index 0. * \param dx stores the difference in the x axis position since the last poll. * \param dy stores the difference in the y axis position since the last poll. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickBalls */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); /** * Get the current state of a POV hat on a joystick. @@ -1030,7 +1036,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, * \param hat the hat index to get the state from; indices start at index 0. * \returns the current hat position. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickHats */ @@ -1052,13 +1058,13 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at * index 0. - * \returns 1 if the specified button is pressed, 0 otherwise. + * \returns true if the button is pressed, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumJoystickButtons */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); +extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); /** * Start a rumble effect. @@ -1075,11 +1081,11 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, * \param high_frequency_rumble the intensity of the high frequency (right) * rumble motor, from 0 to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE, or SDL_FALSE if rumble isn't supported on this joystick. + * \returns true, or false if rumble isn't supported on this joystick. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** * Start a rumble effect in the joystick's triggers. @@ -1101,14 +1107,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, * \param right_rumble the intensity of the right trigger rumble motor, from 0 * to 0xFFFF. * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RumbleJoystick */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); +extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); /** * Update a joystick's LED color. @@ -1123,12 +1129,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *jo * \param red the intensity of the red LED. * \param green the intensity of the green LED. * \param blue the intensity of the blue LED. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); +extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** * Send a joystick specific effect packet. @@ -1136,19 +1142,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, * \param joystick the joystick to affect. * \param data the data to send to the joystick. * \param size the size of the data to send to the joystick. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); +extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); /** * Close a joystick previously opened with SDL_OpenJoystick(). * * \param joystick the joystick device to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenJoystick */ @@ -1162,7 +1168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); @@ -1183,7 +1189,7 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h index ec6c3f2..afa77b6 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keyboard.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeyboard * * SDL keyboard management. + * + * Please refer to the Best Keyboard Practices document for details on how + * best to accept keyboard input in various types of programs: + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keyboard_h_ @@ -31,6 +36,9 @@ #include #include #include +#include +#include +#include #include #include @@ -47,7 +55,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_KeyboardID; @@ -56,13 +64,15 @@ typedef Uint32 SDL_KeyboardID; /** * Return whether a keyboard is currently connected. * - * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise. + * \returns true if a keyboard is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); /** * Get a list of currently connected keyboards. @@ -78,7 +88,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardNameForID * \sa SDL_HasKeyboard @@ -94,7 +106,9 @@ extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); * \returns the name of the selected keyboard or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboards */ @@ -105,7 +119,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID * * \returns the window with keyboard focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); @@ -116,9 +132,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * valid for the whole lifetime of the application and should not be freed by * the caller. * - * A array element with a value of 1 means that the key is pressed and a value - * of 0 means that it is not. Indexes into this array are obtained by using - * SDL_Scancode values. + * A array element with a value of true means that the key is pressed and a + * value of false means that it is not. Indexes into this array are obtained + * by using SDL_Scancode values. * * Use SDL_PumpEvents() to update the state array. * @@ -133,19 +149,23 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); * \param numkeys if non-NULL, receives the length of the returned array. * \returns a pointer to an array of key states. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_PumpEvents * \sa SDL_ResetKeyboard */ -extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys); +extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); /** * Clear the state of the keyboard. * * This function will generate key up events for all pressed keys. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState */ @@ -157,7 +177,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); * \returns an OR'd combination of the modifier keys for the keyboard. See * SDL_Keymod for details. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyboardState * \sa SDL_SetModState @@ -177,7 +199,9 @@ extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); * * \param modstate the desired SDL_Keymod for the keyboard. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetModState */ @@ -189,21 +213,23 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); * * If you want to get the keycode as it would be delivered in key events, * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should - * pass `key_event` as SDL_TRUE. Otherwise this function simply translates the + * pass `key_event` as true. Otherwise this function simply translates the * scancode based on the given modifier state. * * \param scancode the desired SDL_Scancode to query. * \param modstate the modifier state to use when translating the scancode to * a keycode. - * \param key_event SDL_TRUE if the keycode will be used in key events. + * \param key_event true if the keycode will be used in key events. * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyName * \sa SDL_GetScancodeFromKey */ -extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, SDL_bool key_event); +extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); /** * Get the scancode corresponding to the given key code according to the @@ -217,7 +243,9 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scan * scancode generates this key, may be NULL. * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetScancodeName @@ -231,14 +259,16 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, * \param name the name to use for the scancode, encoded as UTF-8. The string * is not copied, so the pointer given to this function must stay * valid while SDL is being used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeName */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); /** * Get a human-readable name for a scancode. @@ -256,7 +286,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, * \returns a pointer to the name for the scancode. If the scancode doesn't * have a name this function returns an empty string (""). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetScancodeFromKey * \sa SDL_GetScancodeFromName @@ -271,7 +303,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scanco * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't * recognized; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetScancodeFromKey @@ -284,10 +318,14 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * * If the key doesn't have a name, this function returns an empty string (""). * + * Letters will be presented in their uppercase form, if applicable. + * * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromName * \sa SDL_GetKeyFromScancode @@ -302,7 +340,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_GetKeyName @@ -319,20 +359,24 @@ extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * \param window the window to enable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInputWithProperties * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); /** * Text input type. @@ -341,7 +385,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInput(SDL_Window *window); * value is valid on every platform, but where a value isn't supported, a * reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -361,12 +405,11 @@ typedef enum SDL_TextInputType /** * Auto capitalization type. * - * These are the valid values for - * SDL_PROP_TEXTINPUT_AUTOCAPITALIZATION_NUMBER. Not every value is valid on - * every platform, but where a value isn't supported, a reasonable fallback - * will be used. + * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. + * Not every value is valid on every platform, but where a value isn't + * supported, a reasonable fallback will be used. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_StartTextInputWithProperties */ @@ -388,7 +431,9 @@ typedef enum SDL_Capitalization * * Text input events are not received by default. * - * On some platforms using this function shows the screen keyboard. + * On some platforms using this function shows the screen keyboard and/or + * activates an IME, which can prevent some key press events from being passed + * through. * * These are the supported properties: * @@ -400,11 +445,11 @@ typedef enum SDL_Capitalization * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail * addresses, usernames, and passwords. * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion - * and auto correction, defaults to SDL_TRUE. + * and auto correction, defaults to true. * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text - * are allowed. This defaults to SDL_TRUE if SDL_HINT_RETURN_KEY_HIDES_IME - * is "0" or is not set, and defaults to SDL_FALSE if - * SDL_HINT_RETURN_KEY_HIDES_IME is "1". + * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is + * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME + * is "1". * * On Android you can directly specify the input type: * @@ -414,17 +459,19 @@ typedef enum SDL_Capitalization * * \param window the window to enable text input. * \param props the properties to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea * \sa SDL_StartTextInput * \sa SDL_StopTextInput * \sa SDL_TextInputActive */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" @@ -436,13 +483,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window * Check whether or not Unicode text input events are enabled for a window. * * \param window the window to check. - * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. + * \returns true if text input events are enabled else false. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); /** * Stop receiving any text input events in a window. @@ -451,28 +500,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window); * it. * * \param window the window to disable text input. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StopTextInput(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); /** * Dismiss the composition window/IME without disabling the subsystem. * * \param window the window to affect. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); /** * Set the area used to type Unicode text input. @@ -485,15 +538,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearComposition(SDL_Window *window); * coordinates, or NULL to clear it. * \param cursor the offset of the current cursor location relative to * `rect->x`, in window coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextInputArea * \sa SDL_StartTextInput */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); /** * Get the area used to type Unicode text input. @@ -505,39 +560,45 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, co * may be NULL. * \param cursor a pointer to the offset of the current cursor location * relative to `rect->x`, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextInputArea */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); /** * Check whether the platform has screen keyboard support. * - * \returns SDL_TRUE if the platform has some screen keyboard support or - * SDL_FALSE if not. + * \returns true if the platform has some screen keyboard support or false if + * not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_ScreenKeyboardShown */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); /** * Check whether the screen keyboard is shown for given window. * * \param window the window for which screen keyboard should be queried. - * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. + * \returns true if screen keyboard is shown or false if not. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasScreenKeyboardSupport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h index 2d03a3d..61b68e7 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_keycode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryKeycode * * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_keycode_h_ @@ -42,272 +47,284 @@ * A special exception is the number keys at the top of the keyboard which map * to SDLK_0...SDLK_9 on AZERTY layouts. * - * \since This datatype is available since SDL 3.0.0. + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_Keycode; -#define SDLK_SCANCODE_MASK (1u<<30) +#define SDLK_EXTENDED_MASK (1u << 29) +#define SDLK_SCANCODE_MASK (1u << 30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -#define SDLK_UNKNOWN 0x00000000u /* 0 */ -#define SDLK_RETURN 0x0000000du /* '\r' */ -#define SDLK_ESCAPE 0x0000001bu /* '\x1B' */ -#define SDLK_BACKSPACE 0x00000008u /* '\b' */ -#define SDLK_TAB 0x00000009u /* '\t' */ -#define SDLK_SPACE 0x00000020u /* ' ' */ -#define SDLK_EXCLAIM 0x00000021u /* '!' */ -#define SDLK_DBLAPOSTROPHE 0x00000022u /* '"' */ -#define SDLK_HASH 0x00000023u /* '#' */ -#define SDLK_DOLLAR 0x00000024u /* '$' */ -#define SDLK_PERCENT 0x00000025u /* '%' */ -#define SDLK_AMPERSAND 0x00000026u /* '&' */ -#define SDLK_APOSTROPHE 0x00000027u /* '\'' */ -#define SDLK_LEFTPAREN 0x00000028u /* '(' */ -#define SDLK_RIGHTPAREN 0x00000029u /* ')' */ -#define SDLK_ASTERISK 0x0000002au /* '*' */ -#define SDLK_PLUS 0x0000002bu /* '+' */ -#define SDLK_COMMA 0x0000002cu /* ',' */ -#define SDLK_MINUS 0x0000002du /* '-' */ -#define SDLK_PERIOD 0x0000002eu /* '.' */ -#define SDLK_SLASH 0x0000002fu /* '/' */ -#define SDLK_0 0x00000030u /* '0' */ -#define SDLK_1 0x00000031u /* '1' */ -#define SDLK_2 0x00000032u /* '2' */ -#define SDLK_3 0x00000033u /* '3' */ -#define SDLK_4 0x00000034u /* '4' */ -#define SDLK_5 0x00000035u /* '5' */ -#define SDLK_6 0x00000036u /* '6' */ -#define SDLK_7 0x00000037u /* '7' */ -#define SDLK_8 0x00000038u /* '8' */ -#define SDLK_9 0x00000039u /* '9' */ -#define SDLK_COLON 0x0000003au /* ':' */ -#define SDLK_SEMICOLON 0x0000003bu /* ';' */ -#define SDLK_LESS 0x0000003cu /* '<' */ -#define SDLK_EQUALS 0x0000003du /* '=' */ -#define SDLK_GREATER 0x0000003eu /* '>' */ -#define SDLK_QUESTION 0x0000003fu /* '?' */ -#define SDLK_AT 0x00000040u /* '@' */ -#define SDLK_LEFTBRACKET 0x0000005bu /* '[' */ -#define SDLK_BACKSLASH 0x0000005cu /* '\\' */ -#define SDLK_RIGHTBRACKET 0x0000005du /* ']' */ -#define SDLK_CARET 0x0000005eu /* '^' */ -#define SDLK_UNDERSCORE 0x0000005fu /* '_' */ -#define SDLK_GRAVE 0x00000060u /* '`' */ -#define SDLK_A 0x00000061u /* 'a' */ -#define SDLK_B 0x00000062u /* 'b' */ -#define SDLK_C 0x00000063u /* 'c' */ -#define SDLK_D 0x00000064u /* 'd' */ -#define SDLK_E 0x00000065u /* 'e' */ -#define SDLK_F 0x00000066u /* 'f' */ -#define SDLK_G 0x00000067u /* 'g' */ -#define SDLK_H 0x00000068u /* 'h' */ -#define SDLK_I 0x00000069u /* 'i' */ -#define SDLK_J 0x0000006au /* 'j' */ -#define SDLK_K 0x0000006bu /* 'k' */ -#define SDLK_L 0x0000006cu /* 'l' */ -#define SDLK_M 0x0000006du /* 'm' */ -#define SDLK_N 0x0000006eu /* 'n' */ -#define SDLK_O 0x0000006fu /* 'o' */ -#define SDLK_P 0x00000070u /* 'p' */ -#define SDLK_Q 0x00000071u /* 'q' */ -#define SDLK_R 0x00000072u /* 'r' */ -#define SDLK_S 0x00000073u /* 's' */ -#define SDLK_T 0x00000074u /* 't' */ -#define SDLK_U 0x00000075u /* 'u' */ -#define SDLK_V 0x00000076u /* 'v' */ -#define SDLK_W 0x00000077u /* 'w' */ -#define SDLK_X 0x00000078u /* 'x' */ -#define SDLK_Y 0x00000079u /* 'y' */ -#define SDLK_Z 0x0000007au /* 'z' */ -#define SDLK_LEFTBRACE 0x0000007bu /* '{' */ -#define SDLK_PIPE 0x0000007cu /* '|' */ -#define SDLK_RIGHTBRACE 0x0000007du /* '}' */ -#define SDLK_TILDE 0x0000007eu /* '~' */ -#define SDLK_DELETE 0x0000007fu /* '\x7F' */ -#define SDLK_PLUSMINUS 0x000000b1u /* '±' */ -#define SDLK_CAPSLOCK 0x40000039u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ -#define SDLK_F1 0x4000003au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ -#define SDLK_F2 0x4000003bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ -#define SDLK_F3 0x4000003cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ -#define SDLK_F4 0x4000003du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ -#define SDLK_F5 0x4000003eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ -#define SDLK_F6 0x4000003fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ -#define SDLK_F7 0x40000040u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ -#define SDLK_F8 0x40000041u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ -#define SDLK_F9 0x40000042u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ -#define SDLK_F10 0x40000043u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ -#define SDLK_F11 0x40000044u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ -#define SDLK_F12 0x40000045u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ -#define SDLK_PRINTSCREEN 0x40000046u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ -#define SDLK_SCROLLLOCK 0x40000047u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ -#define SDLK_PAUSE 0x40000048u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ -#define SDLK_INSERT 0x40000049u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ -#define SDLK_HOME 0x4000004au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ -#define SDLK_PAGEUP 0x4000004bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ -#define SDLK_END 0x4000004du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ -#define SDLK_PAGEDOWN 0x4000004eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ -#define SDLK_RIGHT 0x4000004fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ -#define SDLK_LEFT 0x40000050u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ -#define SDLK_DOWN 0x40000051u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ -#define SDLK_UP 0x40000052u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ -#define SDLK_NUMLOCKCLEAR 0x40000053u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ -#define SDLK_KP_DIVIDE 0x40000054u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ -#define SDLK_KP_MULTIPLY 0x40000055u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ -#define SDLK_KP_MINUS 0x40000056u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ -#define SDLK_KP_PLUS 0x40000057u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ -#define SDLK_KP_ENTER 0x40000058u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ -#define SDLK_KP_1 0x40000059u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ -#define SDLK_KP_2 0x4000005au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ -#define SDLK_KP_3 0x4000005bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ -#define SDLK_KP_4 0x4000005cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ -#define SDLK_KP_5 0x4000005du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ -#define SDLK_KP_6 0x4000005eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ -#define SDLK_KP_7 0x4000005fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ -#define SDLK_KP_8 0x40000060u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ -#define SDLK_KP_9 0x40000061u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ -#define SDLK_KP_0 0x40000062u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ -#define SDLK_KP_PERIOD 0x40000063u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ -#define SDLK_APPLICATION 0x40000065u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ -#define SDLK_POWER 0x40000066u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ -#define SDLK_KP_EQUALS 0x40000067u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ -#define SDLK_F13 0x40000068u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ -#define SDLK_F14 0x40000069u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ -#define SDLK_F15 0x4000006au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ -#define SDLK_F16 0x4000006bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ -#define SDLK_F17 0x4000006cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ -#define SDLK_F18 0x4000006du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ -#define SDLK_F19 0x4000006eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ -#define SDLK_F20 0x4000006fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ -#define SDLK_F21 0x40000070u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ -#define SDLK_F22 0x40000071u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ -#define SDLK_F23 0x40000072u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ -#define SDLK_F24 0x40000073u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ -#define SDLK_EXECUTE 0x40000074u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ -#define SDLK_HELP 0x40000075u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ -#define SDLK_MENU 0x40000076u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ -#define SDLK_SELECT 0x40000077u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ -#define SDLK_STOP 0x40000078u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ -#define SDLK_AGAIN 0x40000079u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ -#define SDLK_UNDO 0x4000007au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ -#define SDLK_CUT 0x4000007bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ -#define SDLK_COPY 0x4000007cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ -#define SDLK_PASTE 0x4000007du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ -#define SDLK_FIND 0x4000007eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ -#define SDLK_MUTE 0x4000007fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ -#define SDLK_VOLUMEUP 0x40000080u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ -#define SDLK_VOLUMEDOWN 0x40000081u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ -#define SDLK_KP_COMMA 0x40000085u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ -#define SDLK_KP_EQUALSAS400 0x40000086u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ -#define SDLK_ALTERASE 0x40000099u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ -#define SDLK_SYSREQ 0x4000009au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ -#define SDLK_CANCEL 0x4000009bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ -#define SDLK_CLEAR 0x4000009cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ -#define SDLK_PRIOR 0x4000009du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ -#define SDLK_RETURN2 0x4000009eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ -#define SDLK_SEPARATOR 0x4000009fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ -#define SDLK_OUT 0x400000a0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ -#define SDLK_OPER 0x400000a1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ -#define SDLK_CLEARAGAIN 0x400000a2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ -#define SDLK_CRSEL 0x400000a3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ -#define SDLK_EXSEL 0x400000a4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ -#define SDLK_KP_00 0x400000b0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ -#define SDLK_KP_000 0x400000b1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ -#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ -#define SDLK_DECIMALSEPARATOR 0x400000b3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ -#define SDLK_CURRENCYUNIT 0x400000b4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ -#define SDLK_CURRENCYSUBUNIT 0x400000b5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ -#define SDLK_KP_LEFTPAREN 0x400000b6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ -#define SDLK_KP_RIGHTPAREN 0x400000b7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ -#define SDLK_KP_LEFTBRACE 0x400000b8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ -#define SDLK_KP_RIGHTBRACE 0x400000b9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ -#define SDLK_KP_TAB 0x400000bau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ -#define SDLK_KP_BACKSPACE 0x400000bbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ -#define SDLK_KP_A 0x400000bcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ -#define SDLK_KP_B 0x400000bdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ -#define SDLK_KP_C 0x400000beu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ -#define SDLK_KP_D 0x400000bfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ -#define SDLK_KP_E 0x400000c0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ -#define SDLK_KP_F 0x400000c1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ -#define SDLK_KP_XOR 0x400000c2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ -#define SDLK_KP_POWER 0x400000c3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ -#define SDLK_KP_PERCENT 0x400000c4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ -#define SDLK_KP_LESS 0x400000c5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ -#define SDLK_KP_GREATER 0x400000c6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ -#define SDLK_KP_AMPERSAND 0x400000c7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ -#define SDLK_KP_DBLAMPERSAND 0x400000c8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ -#define SDLK_KP_VERTICALBAR 0x400000c9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ -#define SDLK_KP_DBLVERTICALBAR 0x400000cau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ -#define SDLK_KP_COLON 0x400000cbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ -#define SDLK_KP_HASH 0x400000ccu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ -#define SDLK_KP_SPACE 0x400000cdu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ -#define SDLK_KP_AT 0x400000ceu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ -#define SDLK_KP_EXCLAM 0x400000cfu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ -#define SDLK_KP_MEMSTORE 0x400000d0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ -#define SDLK_KP_MEMRECALL 0x400000d1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ -#define SDLK_KP_MEMCLEAR 0x400000d2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ -#define SDLK_KP_MEMADD 0x400000d3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ -#define SDLK_KP_MEMSUBTRACT 0x400000d4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ -#define SDLK_KP_MEMMULTIPLY 0x400000d5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ -#define SDLK_KP_MEMDIVIDE 0x400000d6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ -#define SDLK_KP_PLUSMINUS 0x400000d7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ -#define SDLK_KP_CLEAR 0x400000d8u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ -#define SDLK_KP_CLEARENTRY 0x400000d9u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ -#define SDLK_KP_BINARY 0x400000dau /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ -#define SDLK_KP_OCTAL 0x400000dbu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ -#define SDLK_KP_DECIMAL 0x400000dcu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ -#define SDLK_KP_HEXADECIMAL 0x400000ddu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ -#define SDLK_LCTRL 0x400000e0u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ -#define SDLK_LSHIFT 0x400000e1u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ -#define SDLK_LALT 0x400000e2u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ -#define SDLK_LGUI 0x400000e3u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ -#define SDLK_RCTRL 0x400000e4u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ -#define SDLK_RSHIFT 0x400000e5u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ -#define SDLK_RALT 0x400000e6u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ -#define SDLK_RGUI 0x400000e7u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ -#define SDLK_MODE 0x40000101u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ -#define SDLK_SLEEP 0x40000102u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ -#define SDLK_WAKE 0x40000103u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ -#define SDLK_CHANNEL_INCREMENT 0x40000104u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ -#define SDLK_CHANNEL_DECREMENT 0x40000105u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ -#define SDLK_MEDIA_PLAY 0x40000106u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ -#define SDLK_MEDIA_PAUSE 0x40000107u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ -#define SDLK_MEDIA_RECORD 0x40000108u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ -#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ -#define SDLK_MEDIA_REWIND 0x4000010au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ -#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ -#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ -#define SDLK_MEDIA_STOP 0x4000010du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ -#define SDLK_MEDIA_EJECT 0x4000010eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ -#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ -#define SDLK_MEDIA_SELECT 0x40000110u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ -#define SDLK_AC_NEW 0x40000111u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ -#define SDLK_AC_OPEN 0x40000112u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ -#define SDLK_AC_CLOSE 0x40000113u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ -#define SDLK_AC_EXIT 0x40000114u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ -#define SDLK_AC_SAVE 0x40000115u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ -#define SDLK_AC_PRINT 0x40000116u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ -#define SDLK_AC_PROPERTIES 0x40000117u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ -#define SDLK_AC_SEARCH 0x40000118u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ -#define SDLK_AC_HOME 0x40000119u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ -#define SDLK_AC_BACK 0x4000011au /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ -#define SDLK_AC_FORWARD 0x4000011bu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ -#define SDLK_AC_STOP 0x4000011cu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ -#define SDLK_AC_REFRESH 0x4000011du /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ -#define SDLK_AC_BOOKMARKS 0x4000011eu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ -#define SDLK_SOFTLEFT 0x4000011fu /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ -#define SDLK_SOFTRIGHT 0x40000120u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ -#define SDLK_CALL 0x40000121u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ -#define SDLK_ENDCALL 0x40000122u /* SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_UNKNOWN 0x00000000u /**< 0 */ +#define SDLK_RETURN 0x0000000du /**< '\r' */ +#define SDLK_ESCAPE 0x0000001bu /**< '\x1B' */ +#define SDLK_BACKSPACE 0x00000008u /**< '\b' */ +#define SDLK_TAB 0x00000009u /**< '\t' */ +#define SDLK_SPACE 0x00000020u /**< ' ' */ +#define SDLK_EXCLAIM 0x00000021u /**< '!' */ +#define SDLK_DBLAPOSTROPHE 0x00000022u /**< '"' */ +#define SDLK_HASH 0x00000023u /**< '#' */ +#define SDLK_DOLLAR 0x00000024u /**< '$' */ +#define SDLK_PERCENT 0x00000025u /**< '%' */ +#define SDLK_AMPERSAND 0x00000026u /**< '&' */ +#define SDLK_APOSTROPHE 0x00000027u /**< '\'' */ +#define SDLK_LEFTPAREN 0x00000028u /**< '(' */ +#define SDLK_RIGHTPAREN 0x00000029u /**< ')' */ +#define SDLK_ASTERISK 0x0000002au /**< '*' */ +#define SDLK_PLUS 0x0000002bu /**< '+' */ +#define SDLK_COMMA 0x0000002cu /**< ',' */ +#define SDLK_MINUS 0x0000002du /**< '-' */ +#define SDLK_PERIOD 0x0000002eu /**< '.' */ +#define SDLK_SLASH 0x0000002fu /**< '/' */ +#define SDLK_0 0x00000030u /**< '0' */ +#define SDLK_1 0x00000031u /**< '1' */ +#define SDLK_2 0x00000032u /**< '2' */ +#define SDLK_3 0x00000033u /**< '3' */ +#define SDLK_4 0x00000034u /**< '4' */ +#define SDLK_5 0x00000035u /**< '5' */ +#define SDLK_6 0x00000036u /**< '6' */ +#define SDLK_7 0x00000037u /**< '7' */ +#define SDLK_8 0x00000038u /**< '8' */ +#define SDLK_9 0x00000039u /**< '9' */ +#define SDLK_COLON 0x0000003au /**< ':' */ +#define SDLK_SEMICOLON 0x0000003bu /**< ';' */ +#define SDLK_LESS 0x0000003cu /**< '<' */ +#define SDLK_EQUALS 0x0000003du /**< '=' */ +#define SDLK_GREATER 0x0000003eu /**< '>' */ +#define SDLK_QUESTION 0x0000003fu /**< '?' */ +#define SDLK_AT 0x00000040u /**< '@' */ +#define SDLK_LEFTBRACKET 0x0000005bu /**< '[' */ +#define SDLK_BACKSLASH 0x0000005cu /**< '\\' */ +#define SDLK_RIGHTBRACKET 0x0000005du /**< ']' */ +#define SDLK_CARET 0x0000005eu /**< '^' */ +#define SDLK_UNDERSCORE 0x0000005fu /**< '_' */ +#define SDLK_GRAVE 0x00000060u /**< '`' */ +#define SDLK_A 0x00000061u /**< 'a' */ +#define SDLK_B 0x00000062u /**< 'b' */ +#define SDLK_C 0x00000063u /**< 'c' */ +#define SDLK_D 0x00000064u /**< 'd' */ +#define SDLK_E 0x00000065u /**< 'e' */ +#define SDLK_F 0x00000066u /**< 'f' */ +#define SDLK_G 0x00000067u /**< 'g' */ +#define SDLK_H 0x00000068u /**< 'h' */ +#define SDLK_I 0x00000069u /**< 'i' */ +#define SDLK_J 0x0000006au /**< 'j' */ +#define SDLK_K 0x0000006bu /**< 'k' */ +#define SDLK_L 0x0000006cu /**< 'l' */ +#define SDLK_M 0x0000006du /**< 'm' */ +#define SDLK_N 0x0000006eu /**< 'n' */ +#define SDLK_O 0x0000006fu /**< 'o' */ +#define SDLK_P 0x00000070u /**< 'p' */ +#define SDLK_Q 0x00000071u /**< 'q' */ +#define SDLK_R 0x00000072u /**< 'r' */ +#define SDLK_S 0x00000073u /**< 's' */ +#define SDLK_T 0x00000074u /**< 't' */ +#define SDLK_U 0x00000075u /**< 'u' */ +#define SDLK_V 0x00000076u /**< 'v' */ +#define SDLK_W 0x00000077u /**< 'w' */ +#define SDLK_X 0x00000078u /**< 'x' */ +#define SDLK_Y 0x00000079u /**< 'y' */ +#define SDLK_Z 0x0000007au /**< 'z' */ +#define SDLK_LEFTBRACE 0x0000007bu /**< '{' */ +#define SDLK_PIPE 0x0000007cu /**< '|' */ +#define SDLK_RIGHTBRACE 0x0000007du /**< '}' */ +#define SDLK_TILDE 0x0000007eu /**< '~' */ +#define SDLK_DELETE 0x0000007fu /**< '\x7F' */ +#define SDLK_PLUSMINUS 0x000000b1u /**< '\xB1' */ +#define SDLK_CAPSLOCK 0x40000039u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CAPSLOCK) */ +#define SDLK_F1 0x4000003au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F1) */ +#define SDLK_F2 0x4000003bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F2) */ +#define SDLK_F3 0x4000003cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F3) */ +#define SDLK_F4 0x4000003du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F4) */ +#define SDLK_F5 0x4000003eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F5) */ +#define SDLK_F6 0x4000003fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F6) */ +#define SDLK_F7 0x40000040u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F7) */ +#define SDLK_F8 0x40000041u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F8) */ +#define SDLK_F9 0x40000042u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F9) */ +#define SDLK_F10 0x40000043u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F10) */ +#define SDLK_F11 0x40000044u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F11) */ +#define SDLK_F12 0x40000045u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F12) */ +#define SDLK_PRINTSCREEN 0x40000046u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRINTSCREEN) */ +#define SDLK_SCROLLLOCK 0x40000047u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SCROLLLOCK) */ +#define SDLK_PAUSE 0x40000048u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAUSE) */ +#define SDLK_INSERT 0x40000049u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT) */ +#define SDLK_HOME 0x4000004au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME) */ +#define SDLK_PAGEUP 0x4000004bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP) */ +#define SDLK_END 0x4000004du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END) */ +#define SDLK_PAGEDOWN 0x4000004eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN) */ +#define SDLK_RIGHT 0x4000004fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT) */ +#define SDLK_LEFT 0x40000050u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LEFT) */ +#define SDLK_DOWN 0x40000051u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DOWN) */ +#define SDLK_UP 0x40000052u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UP) */ +#define SDLK_NUMLOCKCLEAR 0x40000053u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_NUMLOCKCLEAR) */ +#define SDLK_KP_DIVIDE 0x40000054u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DIVIDE) */ +#define SDLK_KP_MULTIPLY 0x40000055u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MULTIPLY) */ +#define SDLK_KP_MINUS 0x40000056u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MINUS) */ +#define SDLK_KP_PLUS 0x40000057u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUS) */ +#define SDLK_KP_ENTER 0x40000058u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_ENTER) */ +#define SDLK_KP_1 0x40000059u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_1) */ +#define SDLK_KP_2 0x4000005au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_2) */ +#define SDLK_KP_3 0x4000005bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_3) */ +#define SDLK_KP_4 0x4000005cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_4) */ +#define SDLK_KP_5 0x4000005du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_5) */ +#define SDLK_KP_6 0x4000005eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_6) */ +#define SDLK_KP_7 0x4000005fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_7) */ +#define SDLK_KP_8 0x40000060u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_8) */ +#define SDLK_KP_9 0x40000061u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_9) */ +#define SDLK_KP_0 0x40000062u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_0) */ +#define SDLK_KP_PERIOD 0x40000063u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERIOD) */ +#define SDLK_APPLICATION 0x40000065u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APPLICATION) */ +#define SDLK_POWER 0x40000066u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_POWER) */ +#define SDLK_KP_EQUALS 0x40000067u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALS) */ +#define SDLK_F13 0x40000068u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F13) */ +#define SDLK_F14 0x40000069u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F14) */ +#define SDLK_F15 0x4000006au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F15) */ +#define SDLK_F16 0x4000006bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F16) */ +#define SDLK_F17 0x4000006cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F17) */ +#define SDLK_F18 0x4000006du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F18) */ +#define SDLK_F19 0x4000006eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F19) */ +#define SDLK_F20 0x4000006fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F20) */ +#define SDLK_F21 0x40000070u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F21) */ +#define SDLK_F22 0x40000071u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F22) */ +#define SDLK_F23 0x40000072u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F23) */ +#define SDLK_F24 0x40000073u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_F24) */ +#define SDLK_EXECUTE 0x40000074u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXECUTE) */ +#define SDLK_HELP 0x40000075u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HELP) */ +#define SDLK_MENU 0x40000076u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MENU) */ +#define SDLK_SELECT 0x40000077u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SELECT) */ +#define SDLK_STOP 0x40000078u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_STOP) */ +#define SDLK_AGAIN 0x40000079u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AGAIN) */ +#define SDLK_UNDO 0x4000007au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_UNDO) */ +#define SDLK_CUT 0x4000007bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CUT) */ +#define SDLK_COPY 0x4000007cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_COPY) */ +#define SDLK_PASTE 0x4000007du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PASTE) */ +#define SDLK_FIND 0x4000007eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_FIND) */ +#define SDLK_MUTE 0x4000007fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MUTE) */ +#define SDLK_VOLUMEUP 0x40000080u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEUP) */ +#define SDLK_VOLUMEDOWN 0x40000081u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_VOLUMEDOWN) */ +#define SDLK_KP_COMMA 0x40000085u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COMMA) */ +#define SDLK_KP_EQUALSAS400 0x40000086u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EQUALSAS400) */ +#define SDLK_ALTERASE 0x40000099u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ALTERASE) */ +#define SDLK_SYSREQ 0x4000009au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SYSREQ) */ +#define SDLK_CANCEL 0x4000009bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CANCEL) */ +#define SDLK_CLEAR 0x4000009cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEAR) */ +#define SDLK_PRIOR 0x4000009du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PRIOR) */ +#define SDLK_RETURN2 0x4000009eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RETURN2) */ +#define SDLK_SEPARATOR 0x4000009fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SEPARATOR) */ +#define SDLK_OUT 0x400000a0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OUT) */ +#define SDLK_OPER 0x400000a1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_OPER) */ +#define SDLK_CLEARAGAIN 0x400000a2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CLEARAGAIN) */ +#define SDLK_CRSEL 0x400000a3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CRSEL) */ +#define SDLK_EXSEL 0x400000a4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_EXSEL) */ +#define SDLK_KP_00 0x400000b0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_00) */ +#define SDLK_KP_000 0x400000b1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_000) */ +#define SDLK_THOUSANDSSEPARATOR 0x400000b2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_THOUSANDSSEPARATOR) */ +#define SDLK_DECIMALSEPARATOR 0x400000b3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_DECIMALSEPARATOR) */ +#define SDLK_CURRENCYUNIT 0x400000b4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYUNIT) */ +#define SDLK_CURRENCYSUBUNIT 0x400000b5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CURRENCYSUBUNIT) */ +#define SDLK_KP_LEFTPAREN 0x400000b6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTPAREN) */ +#define SDLK_KP_RIGHTPAREN 0x400000b7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTPAREN) */ +#define SDLK_KP_LEFTBRACE 0x400000b8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LEFTBRACE) */ +#define SDLK_KP_RIGHTBRACE 0x400000b9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_RIGHTBRACE) */ +#define SDLK_KP_TAB 0x400000bau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_TAB) */ +#define SDLK_KP_BACKSPACE 0x400000bbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BACKSPACE) */ +#define SDLK_KP_A 0x400000bcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_A) */ +#define SDLK_KP_B 0x400000bdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_B) */ +#define SDLK_KP_C 0x400000beu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_C) */ +#define SDLK_KP_D 0x400000bfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_D) */ +#define SDLK_KP_E 0x400000c0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_E) */ +#define SDLK_KP_F 0x400000c1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_F) */ +#define SDLK_KP_XOR 0x400000c2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_XOR) */ +#define SDLK_KP_POWER 0x400000c3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_POWER) */ +#define SDLK_KP_PERCENT 0x400000c4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PERCENT) */ +#define SDLK_KP_LESS 0x400000c5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_LESS) */ +#define SDLK_KP_GREATER 0x400000c6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_GREATER) */ +#define SDLK_KP_AMPERSAND 0x400000c7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AMPERSAND) */ +#define SDLK_KP_DBLAMPERSAND 0x400000c8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLAMPERSAND) */ +#define SDLK_KP_VERTICALBAR 0x400000c9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_VERTICALBAR) */ +#define SDLK_KP_DBLVERTICALBAR 0x400000cau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DBLVERTICALBAR) */ +#define SDLK_KP_COLON 0x400000cbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_COLON) */ +#define SDLK_KP_HASH 0x400000ccu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HASH) */ +#define SDLK_KP_SPACE 0x400000cdu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_SPACE) */ +#define SDLK_KP_AT 0x400000ceu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_AT) */ +#define SDLK_KP_EXCLAM 0x400000cfu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_EXCLAM) */ +#define SDLK_KP_MEMSTORE 0x400000d0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSTORE) */ +#define SDLK_KP_MEMRECALL 0x400000d1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMRECALL) */ +#define SDLK_KP_MEMCLEAR 0x400000d2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMCLEAR) */ +#define SDLK_KP_MEMADD 0x400000d3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMADD) */ +#define SDLK_KP_MEMSUBTRACT 0x400000d4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMSUBTRACT) */ +#define SDLK_KP_MEMMULTIPLY 0x400000d5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMMULTIPLY) */ +#define SDLK_KP_MEMDIVIDE 0x400000d6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_MEMDIVIDE) */ +#define SDLK_KP_PLUSMINUS 0x400000d7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_PLUSMINUS) */ +#define SDLK_KP_CLEAR 0x400000d8u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEAR) */ +#define SDLK_KP_CLEARENTRY 0x400000d9u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_CLEARENTRY) */ +#define SDLK_KP_BINARY 0x400000dau /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_BINARY) */ +#define SDLK_KP_OCTAL 0x400000dbu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_OCTAL) */ +#define SDLK_KP_DECIMAL 0x400000dcu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_DECIMAL) */ +#define SDLK_KP_HEXADECIMAL 0x400000ddu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_KP_HEXADECIMAL) */ +#define SDLK_LCTRL 0x400000e0u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LCTRL) */ +#define SDLK_LSHIFT 0x400000e1u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LSHIFT) */ +#define SDLK_LALT 0x400000e2u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LALT) */ +#define SDLK_LGUI 0x400000e3u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_LGUI) */ +#define SDLK_RCTRL 0x400000e4u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RCTRL) */ +#define SDLK_RSHIFT 0x400000e5u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RSHIFT) */ +#define SDLK_RALT 0x400000e6u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RALT) */ +#define SDLK_RGUI 0x400000e7u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RGUI) */ +#define SDLK_MODE 0x40000101u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MODE) */ +#define SDLK_SLEEP 0x40000102u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SLEEP) */ +#define SDLK_WAKE 0x40000103u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_WAKE) */ +#define SDLK_CHANNEL_INCREMENT 0x40000104u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_INCREMENT) */ +#define SDLK_CHANNEL_DECREMENT 0x40000105u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CHANNEL_DECREMENT) */ +#define SDLK_MEDIA_PLAY 0x40000106u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY) */ +#define SDLK_MEDIA_PAUSE 0x40000107u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PAUSE) */ +#define SDLK_MEDIA_RECORD 0x40000108u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_RECORD) */ +#define SDLK_MEDIA_FAST_FORWARD 0x40000109u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_FAST_FORWARD) */ +#define SDLK_MEDIA_REWIND 0x4000010au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_REWIND) */ +#define SDLK_MEDIA_NEXT_TRACK 0x4000010bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_NEXT_TRACK) */ +#define SDLK_MEDIA_PREVIOUS_TRACK 0x4000010cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PREVIOUS_TRACK) */ +#define SDLK_MEDIA_STOP 0x4000010du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_STOP) */ +#define SDLK_MEDIA_EJECT 0x4000010eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_EJECT) */ +#define SDLK_MEDIA_PLAY_PAUSE 0x4000010fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_PLAY_PAUSE) */ +#define SDLK_MEDIA_SELECT 0x40000110u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_MEDIA_SELECT) */ +#define SDLK_AC_NEW 0x40000111u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_NEW) */ +#define SDLK_AC_OPEN 0x40000112u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_OPEN) */ +#define SDLK_AC_CLOSE 0x40000113u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_CLOSE) */ +#define SDLK_AC_EXIT 0x40000114u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_EXIT) */ +#define SDLK_AC_SAVE 0x40000115u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SAVE) */ +#define SDLK_AC_PRINT 0x40000116u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PRINT) */ +#define SDLK_AC_PROPERTIES 0x40000117u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_PROPERTIES) */ +#define SDLK_AC_SEARCH 0x40000118u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_SEARCH) */ +#define SDLK_AC_HOME 0x40000119u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_HOME) */ +#define SDLK_AC_BACK 0x4000011au /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BACK) */ +#define SDLK_AC_FORWARD 0x4000011bu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_FORWARD) */ +#define SDLK_AC_STOP 0x4000011cu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_STOP) */ +#define SDLK_AC_REFRESH 0x4000011du /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_REFRESH) */ +#define SDLK_AC_BOOKMARKS 0x4000011eu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AC_BOOKMARKS) */ +#define SDLK_SOFTLEFT 0x4000011fu /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT) */ +#define SDLK_SOFTRIGHT 0x40000120u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) */ +#define SDLK_CALL 0x40000121u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) */ +#define SDLK_ENDCALL 0x40000122u /**< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) */ +#define SDLK_LEFT_TAB 0x20000001u /**< Extended key Left Tab */ +#define SDLK_LEVEL5_SHIFT 0x20000002u /**< Extended key Level 5 Shift */ +#define SDLK_MULTI_KEY_COMPOSE 0x20000003u /**< Extended key Multi-key Compose */ +#define SDLK_LMETA 0x20000004u /**< Extended key Left Meta */ +#define SDLK_RMETA 0x20000005u /**< Extended key Right Meta */ +#define SDLK_LHYPER 0x20000006u /**< Extended key Left Hyper */ +#define SDLK_RHYPER 0x20000007u /**< Extended key Right Hyper */ /** * Valid key modifiers (possibly OR'd together). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint16 SDL_Keymod; #define SDL_KMOD_NONE 0x0000u /**< no modifier is applicable. */ #define SDL_KMOD_LSHIFT 0x0001u /**< the left Shift key is down. */ #define SDL_KMOD_RSHIFT 0x0002u /**< the right Shift key is down. */ +#define SDL_KMOD_LEVEL5 0x0004u /**< the Level 5 Shift key is down. */ #define SDL_KMOD_LCTRL 0x0040u /**< the left Ctrl (Control) key is down. */ #define SDL_KMOD_RCTRL 0x0080u /**< the right Ctrl (Control) key is down. */ #define SDL_KMOD_LALT 0x0100u /**< the left Alt key is down. */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h index ab34a38..f8649d7 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_loadso.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ * * System-dependent library loading routines. * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * * Some things to keep in mind: * * - These functions only work on C function names. Other languages may have @@ -38,6 +46,11 @@ * not defined whether or not it goes into the global symbol namespace for * the application. If it does and it conflicts with symbols in your code or * other shared libraries, you will not get the results you expect. :) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that pointer after the library unloads. */ #ifndef SDL_loadso_h_ @@ -52,6 +65,17 @@ extern "C" { #endif +/** + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + */ +typedef struct SDL_SharedObject SDL_SharedObject; + /** * Dynamically load a shared object. * @@ -59,12 +83,14 @@ extern "C" { * \returns an opaque pointer to the object handle or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFunction * \sa SDL_UnloadObject */ -extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); +extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile); /** * Look up the address of the named function in a shared object. @@ -86,22 +112,29 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile); * \returns a pointer to the function or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(void *handle, const char *name); +extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name); /** * Unload a shared object from memory. * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * * \param handle a valid shared object handle returned by SDL_LoadObject(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadObject */ -extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(void *handle); +extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h index 85d7750..902843e 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_locale.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategoryLocale * * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. */ #ifndef SDL_locale_h @@ -47,7 +53,7 @@ extern "C" { * would be "en"), and the country, if not NULL, will be an ISO-3166 country * code (so Canada would be "CA"). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPreferredLocales */ @@ -96,7 +102,7 @@ typedef struct SDL_Locale * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h index deda238..a56476c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_log.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,7 @@ /** * # CategoryLog * - * Simple log messages with priorities and categories. A message’s + * Simple log messages with priorities and categories. A message's * SDL_LogPriority signifies how important the message is. A message's * SDL_LogCategory signifies from what domain it belongs to. Every category * has a minimum priority specified: when a message belongs to that category, @@ -76,7 +76,7 @@ extern "C" { * level, the assert category is enabled at the WARN level, test is enabled at * the VERBOSE level and all other categories are enabled at the ERROR level. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogCategory { @@ -87,12 +87,11 @@ typedef enum SDL_LogCategory SDL_LOG_CATEGORY_AUDIO, SDL_LOG_CATEGORY_VIDEO, SDL_LOG_CATEGORY_RENDER, - SDL_LOG_CATEGORY_GPU, SDL_LOG_CATEGORY_INPUT, SDL_LOG_CATEGORY_TEST, + SDL_LOG_CATEGORY_GPU, /* Reserved for future SDL library use */ - SDL_LOG_CATEGORY_RESERVED1, SDL_LOG_CATEGORY_RESERVED2, SDL_LOG_CATEGORY_RESERVED3, SDL_LOG_CATEGORY_RESERVED4, @@ -117,17 +116,19 @@ typedef enum SDL_LogCategory /** * The predefined log priorities * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_LogPriority { - SDL_LOG_PRIORITY_VERBOSE = 1, + SDL_LOG_PRIORITY_INVALID, + SDL_LOG_PRIORITY_TRACE, + SDL_LOG_PRIORITY_VERBOSE, SDL_LOG_PRIORITY_DEBUG, SDL_LOG_PRIORITY_INFO, SDL_LOG_PRIORITY_WARN, SDL_LOG_PRIORITY_ERROR, SDL_LOG_PRIORITY_CRITICAL, - SDL_NUM_LOG_PRIORITIES + SDL_LOG_PRIORITY_COUNT } SDL_LogPriority; @@ -136,7 +137,9 @@ typedef enum SDL_LogPriority * * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriority @@ -149,14 +152,15 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriorities(SDL_LogPriority priority); * \param category the category to assign a priority to. * \param priority the SDL_LogPriority to assign. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetLogPriority * \sa SDL_ResetLogPriorities * \sa SDL_SetLogPriorities */ -extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, - SDL_LogPriority priority); +extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, SDL_LogPriority priority); /** * Get the priority of a particular log category. @@ -164,7 +168,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetLogPriority(int category, * \param category the category to query. * \returns the SDL_LogPriority for the requested category. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriority */ @@ -175,7 +181,9 @@ extern SDL_DECLSPEC SDL_LogPriority SDLCALL SDL_GetLogPriority(int category); * * This is called by SDL_Quit(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority @@ -192,15 +200,17 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetLogPriorities(void); * \param priority the SDL_LogPriority to modify. * \param prefix the prefix to use for that log priority, or NULL to use no * prefix. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetLogPriorities * \sa SDL_SetLogPriority */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority priority, const char *prefix); /** * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. @@ -209,7 +219,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \param ... additional parameters matching % tokens in the `fmt` string, if * any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LogCritical * \sa SDL_LogDebug @@ -217,11 +229,37 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLogPriorityPrefix(SDL_LogPriority pr * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); +/** + * Log a message with SDL_LOG_PRIORITY_TRACE. + * + * \param category the category of the message. + * \param fmt a printf() style message format string. + * \param ... additional parameters matching % tokens in the **fmt** string, + * if any. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Log + * \sa SDL_LogCritical + * \sa SDL_LogDebug + * \sa SDL_LogError + * \sa SDL_LogInfo + * \sa SDL_LogMessage + * \sa SDL_LogMessageV + * \sa SDL_LogTrace + * \sa SDL_LogVerbose + * \sa SDL_LogWarn + */ +extern SDL_DECLSPEC void SDLCALL SDL_LogTrace(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + /** * Log a message with SDL_LOG_PRIORITY_VERBOSE. * @@ -230,7 +268,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fm * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -251,7 +291,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -259,6 +301,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_ * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -272,7 +315,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -280,6 +325,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogError * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -293,7 +339,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -302,6 +350,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose */ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); @@ -314,7 +363,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -322,6 +373,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STR * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -335,7 +387,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogDebug @@ -343,6 +397,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_ST * \sa SDL_LogInfo * \sa SDL_LogMessage * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -357,7 +412,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \param ... additional parameters matching % tokens in the **fmt** string, * if any. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -365,6 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessageV + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -380,7 +438,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \param fmt a printf() style message format string. * \param ap a variable argument list. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Log * \sa SDL_LogCritical @@ -388,6 +448,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessage(int category, * \sa SDL_LogError * \sa SDL_LogInfo * \sa SDL_LogMessage + * \sa SDL_LogTrace * \sa SDL_LogVerbose * \sa SDL_LogWarn */ @@ -398,7 +459,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, /** * The prototype for the log output callback function. * - * This function is called by SDL when there is new text to be logged. + * This function is called by SDL when there is new text to be logged. A mutex + * is held so that this function is never called by more than one thread at + * once. * * \param userdata what was passed as `userdata` to * SDL_SetLogOutputFunction(). @@ -406,10 +469,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LogMessageV(int category, * \param priority the priority of the message. * \param message the message being output. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); +/** + * Get the default log output function. + * + * \returns the default log output callback. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetLogOutputFunction + * \sa SDL_GetLogOutputFunction + */ +extern SDL_DECLSPEC SDL_LogOutputFunction SDLCALL SDL_GetDefaultLogOutputFunction(void); + /** * Get the current log output function. * @@ -418,8 +495,11 @@ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_ * \param userdata a pointer filled in with the pointer that is passed to * `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_SetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction *callback, void **userdata); @@ -430,8 +510,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetLogOutputFunction(SDL_LogOutputFunction * \param callback an SDL_LogOutputFunction to call instead of the default. * \param userdata a pointer that is passed to `callback`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetDefaultLogOutputFunction * \sa SDL_GetLogOutputFunction */ extern SDL_DECLSPEC void SDLCALL SDL_SetLogOutputFunction(SDL_LogOutputFunction callback, void *userdata); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h index de3c187..2e7a2eb 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,13 +22,29 @@ /** * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() if necessary so that it is called by SDL. * - * For details on how SDL_main works, and how to use it, please refer to: + * In order to make this consistent on all platforms, the application's main() + * should look like this: + * + * ```c + * int main(int argc, char *argv[]) + * { + * } + * ``` + * + * SDL will take care of platform specific details on how it gets called. + * + * This is also where an app can be configured to use the main callbacks, via + * the SDL_MAIN_USE_CALLBACKS macro. + * + * This is a "single-header library," which is to say that including this + * header inserts code into your program, and you should only include it once + * in most cases. SDL.h does not include this header automatically. + * + * For more information, see: * * https://wiki.libsdl.org/SDL3/README/main-functions - * - * (or docs/README-main-functions.md in the SDL source tree) */ #ifndef SDL_main_h_ @@ -39,8 +55,96 @@ #include #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Inform SDL that the app is providing an entry point instead of SDL. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide the + * proper entry point for the platform, and all the other magic details + * needed, like manually calling SDL_SetMainReady. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + */ +#define SDL_MAIN_HANDLED 1 + +/** + * Inform SDL to use the main callbacks instead of main. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide + * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and + * SDL_AppQuit. The app should not provide a `main` function in this case, and + * doing so will likely cause the build to fail. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.2.0. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + * \sa SDL_AppIterate + * \sa SDL_AppQuit + */ +#define SDL_MAIN_USE_CALLBACKS 1 + +/** + * Defined if the target platform offers a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if available, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_AVAILABLE + +/** + * Defined if the target platform _requires_ a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if required, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_MAIN_NEEDED + +#endif + +#if defined(__has_include) + #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h") + #define SDL_PLATFORM_PRIVATE_MAIN + #endif +#endif + #ifndef SDL_MAIN_HANDLED - #ifdef SDL_PLATFORM_WIN32 + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_private.h" + + #elif defined(SDL_PLATFORM_WIN32) /* On Windows SDL provides WinMain(), which parses the command line and passes the arguments to your main function. @@ -48,20 +152,6 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_WINRT) - /* On WinRT, SDL provides a main function that initializes CoreApplication, - creating an instance of IFrameworkView in the process. - - 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 ` - 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 - #elif defined(SDL_PLATFORM_GDK) /* On GDK, SDL provides a main function that initializes the game runtime. @@ -91,8 +181,14 @@ */ #define SDL_MAIN_NEEDED - /* We need to export SDL_main so it can be launched from Java */ - #define SDLMAIN_DECLSPEC SDL_DECLSPEC + /* As this is launched from Java, the real entry point (main() function) + is outside of the the binary built from this code. + This define makes sure that, unlike on other platforms, SDL_main.h + and SDL_main_impl.h export an `SDL_main()` function (to be called + from Java), but don't implement a native `int main(int argc, char* argv[])` + or similar. + */ + #define SDL_MAIN_EXPORTED #elif defined(SDL_PLATFORM_EMSCRIPTEN) /* On Emscripten, SDL provides a main function that converts URL @@ -129,60 +225,36 @@ */ #define SDL_MAIN_AVAILABLE - #elif defined(SDL_PLATFORM_NGAGE) - /* - TODO: not sure if it should be SDL_MAIN_NEEDED, in SDL2 ngage had a - main implementation, but wasn't mentioned in SDL_main.h - */ - #define SDL_MAIN_AVAILABLE - #endif #endif /* SDL_MAIN_HANDLED */ -#ifndef SDLMAIN_DECLSPEC -#define SDLMAIN_DECLSPEC -#endif - -/** - * \file SDL_main.h - * - * The application's main() function must be called with C linkage, - * and should be declared like this: - * - * ```c - * #ifdef __cplusplus - * extern "C" - * #endif - * int main(int argc, char *argv[]) - * { - * } - * ``` - */ #ifdef SDL_WIKI_DOCUMENTATION_SECTION /** - * Inform SDL to use the main callbacks instead of main. + * A macro to tag a main entry point function as exported. * - * SDL does not define this macro, but will check if it is defined when - * including `SDL_main.h`. If defined, SDL will expect the app to provide - * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and - * SDL_AppQuit. The app should not provide a `main` function in this case, and - * doing so will likely cause the build to fail. + * Most platforms don't need this, and the macro will be defined to nothing. + * Some, like Android, keep the entry points in a shared library and need to + * explicitly export the symbols. * - * Please see [README/main-functions](README/main-functions), (or - * docs/README-main-functions.md in the source tree) for a more detailed - * explanation. + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. * - * \since This macro is used by the headers since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit + * \sa SDL_DECLSPEC */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif +#define SDLMAIN_DECLSPEC + +#elif defined(SDL_MAIN_EXPORTED) +/* We need to export SDL_main so it can be launched from external code, + like SDLActivity.java on Android */ +#define SDLMAIN_DECLSPEC SDL_DECLSPEC +#else +/* usually this is empty */ +#define SDLMAIN_DECLSPEC +#endif /* SDL_MAIN_EXPORTED */ #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main @@ -248,6 +320,8 @@ extern "C" { * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code * that reports success to the platform. * + * This function is called by SDL on the main thread. + * * \param appstate a place where the app can optionally store a pointer for * future use. * \param argc the standard ANSI C main's argc; number of elements in `argv`. @@ -256,9 +330,7 @@ extern "C" { * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppIterate * \sa SDL_AppEvent @@ -301,13 +373,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int a * SDL_AppQuit and terminates with an exit code that reports success to the * platform. * + * This function is called by SDL on the main thread. + * * \param appstate an optional pointer, provided by the app in SDL_AppInit. * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with SDL_AppEvent() + * for events not pushed on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppEvent @@ -320,15 +395,15 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a * standard "main" function, you should not supply this. * - * This function is called as needed by SDL after SDL_AppInit returns 0; It is - * called once for each new event. + * This function is called as needed by SDL after SDL_AppInit returns + * SDL_APP_CONTINUE. It is called once for each new event. * * There is (currently) no guarantee about what thread this will be called * from; whatever thread pushes an event onto SDL's queue will trigger this * function. SDL is responsible for pumping the event queue between each call * to SDL_AppIterate, so in normal operation one should only get events in a * serial fashion, but be careful if you have a thread that explicitly calls - * SDL_PushEvent. + * SDL_PushEvent. SDL itself will push events to the queue on the main thread. * * Events sent to this function are not owned by the app; if you need to save * the data, you should copy it. @@ -352,14 +427,16 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate); * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * - * \threadsafety This function is not thread safe. + * \threadsafety This function may get called concurrently with + * SDL_AppIterate() or SDL_AppQuit() for events not pushed from + * the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AppInit * \sa SDL_AppIterate */ -extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event); +extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event); /** * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps. @@ -385,15 +462,19 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, const * function call is the last time this pointer will be provided, so any * resources to it should be cleaned up here. * + * This function is called by SDL on the main thread. + * * \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. + * \threadsafety SDL_AppEvent() may get called concurrently with this function + * if other threads that push events are still active. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.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 */ @@ -407,7 +488,7 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate); * program completion, and small non-zero values are considered * errors. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); @@ -440,7 +521,7 @@ typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); * * \threadsafety This is the program entry point. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); @@ -453,7 +534,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); * will not be changed it is necessary to define SDL_MAIN_HANDLED before * including SDL.h. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init */ @@ -485,7 +566,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void); * \threadsafety Generally this is called once, near startup, from the * process's initial thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved); @@ -512,12 +593,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func * \threadsafety It is not safe to call this anywhere except as the only * function call in SDL_main. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit); -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) /** * Register a win32 window class for SDL's use. @@ -538,12 +619,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * what is specified here. * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL * will use `GetModuleHandle(NULL)` instead. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); +extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); /** * Deregister the win32 window class from an SDL_RegisterApp call. @@ -558,23 +639,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RegisterApp(const char *name, Uint32 st * deregistered when the registration counter in SDL_RegisterApp decrements to * zero through calls to this function. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ - -#ifdef SDL_PLATFORM_GDK +#endif /* defined(SDL_PLATFORM_WINDOWS) */ /** * Callback from the application to let the suspend continue. * - * \since This function is available since SDL 3.0.0. + * This function is only needed for Xbox GDK support; all other platforms will + * do nothing and set an "unsupported" error message. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); -#endif /* SDL_PLATFORM_GDK */ - #ifdef __cplusplus } #endif @@ -583,29 +663,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL) /* include header-only SDL_main implementations */ - #if defined(SDL_MAIN_USE_CALLBACKS) \ - || defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) || defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS) \ - || defined(SDL_PLATFORM_3DS) || defined(SDL_PLATFORM_NGAGE) || defined(SDL_PLATFORM_PS2) || defined(SDL_PLATFORM_PSP) \ - || defined(SDL_PLATFORM_EMSCRIPTEN) - + #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) /* platforms which main (-equivalent) can be implemented in plain C */ #include - - #elif defined(SDL_PLATFORM_WINRT) /* C++ platforms */ - #ifdef __cplusplus - #include - #else - /* Note: to get rid of the following warning, you can #define SDL_MAIN_NOIMPL before including SDL_main.h - * in your C sourcefile that contains the standard main. Do *not* use SDL_MAIN_HANDLED for that, then SDL_main won't find your main()! - */ - #ifdef _MSC_VER - #pragma message("Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C (then continue including SDL_main.h there!) and create a fresh .cpp file that only contains #include ") - #elif defined(__GNUC__) /* gcc, clang, mingw and compatible are matched by this and have #warning */ - #warning "Note: Your platform needs the SDL_main implementation in a C++ source file. You can keep your main() in plain C and create a fresh .cpp file that only contains #include " - #endif /* __GNUC__ */ - #endif /* __cplusplus */ - - #endif /* C++ platforms like SDL_PLATFORM_WINRT etc */ + #endif #endif #endif /* SDL_main_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h index ad122df..14ebb42 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_main_impl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,7 +29,7 @@ #endif /* if someone wants to include SDL_main.h but doesn't want the main handing magic, - (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first + (maybe to call SDL_RegisterApp()) they can #define SDL_MAIN_HANDLED first. SDL_MAIN_NOIMPL is for SDL-internal usage (only affects implementation, not definition of SDL_MAIN_AVAILABLE etc in SDL_main.h) and if the user wants to have the SDL_main implementation (from this header) in another source file @@ -64,10 +64,15 @@ #endif /* SDL_MAIN_USE_CALLBACKS */ - /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */ - #if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) + /* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point, + unless the real entry point needs to be somewhere else entirely, like Android where it's in Java code */ + #if (!defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)) && !defined(SDL_MAIN_EXPORTED) - #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) + #if defined(SDL_PLATFORM_PRIVATE_MAIN) + /* Private platforms may have their own ideas about entry points. */ + #include "SDL_main_impl_private.h" + + #elif defined(SDL_PLATFORM_WINDOWS) /* these defines/typedefs are needed for the WinMain() definition */ #ifndef WINAPI @@ -82,7 +87,7 @@ #if defined(_MSC_VER) && !defined(SDL_PLATFORM_GDK) /* This is where execution begins [console apps] */ - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int wmain(int argc, wchar_t *wargv[], wchar_t *wenvp) { (void)argc; @@ -107,7 +112,7 @@ extern "C" { #endif - #if defined( UNICODE ) && UNICODE + #if defined(UNICODE) && UNICODE int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw) #else /* ANSI */ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw) @@ -124,83 +129,7 @@ } /* extern "C" */ #endif - /* end of SDL_PLATFORM_WIN32 and SDL_PLATFORM_GDK impls */ - - #elif defined(SDL_PLATFORM_WINRT) - - /* WinRT main based on SDL_winrt_main_NonXAML.cpp, placed in the public domain by David Ludwig 3/13/14 */ - - #include - - /* At least one file in any SDL/WinRT app appears to require compilation - with C++/CX, otherwise a Windows Metadata file won't get created, and - an APPX0702 build error can appear shortly after linking. - - The following set of preprocessor code forces this file to be compiled - as C++/CX, which appears to cause Visual C++ 2012's build tools to - create this .winmd file, and will help allow builds of SDL/WinRT apps - to proceed without error. - - If other files in an app's project enable C++/CX compilation, then it might - be possible for the .cpp file including SDL_main.h to be compiled without /ZW, - for Visual C++'s build tools to create a winmd file, and for the app to - build without APPX0702 errors. In this case, if - SDL_WINRT_METADATA_FILE_AVAILABLE is defined as a C/C++ macro, then - the #error (to force C++/CX compilation) will be disabled. - - Please note that /ZW can be specified on a file-by-file basis. To do this, - right click on the file in Visual C++, click Properties, then change the - setting through the dialog that comes up. - */ - #ifndef SDL_WINRT_METADATA_FILE_AVAILABLE - #if !defined(__cplusplus) || (!defined(__cplusplus_winrt) && _MSVC_LANG < 202002L) - #error The C++ file that includes SDL_main.h must be compiled as C++ code with /ZW, otherwise build errors due to missing .winmd files can occur. - #endif - #endif - - /* Prevent MSVC++ from warning about threading models when defining our - custom WinMain. The threading model will instead be set via a direct - call to Windows::Foundation::Initialize (rather than via an attributed - function). - - To note, this warning (C4447) does not seem to come up unless this file - is compiled with C++/CX enabled (via the /ZW compiler flag). - */ - #ifdef _MSC_VER - #pragma warning(disable : 4447) - /* Make sure the function to initialize the Windows Runtime gets linked in. */ - #pragma comment(lib, "runtimeobject.lib") - #endif - - #ifdef __cplusplus - extern "C" { - #endif - int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int) - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - #if _MSVC_LANG >= 202002L - int main(int argc, char** argv) { - return SDL_RunApp(argc, argv, SDL_main, NULL); - } - #endif - #ifdef __cplusplus - } /* extern "C" */ - #endif - - /* end of WinRT impl */ - - #elif defined(SDL_PLATFORM_NGAGE) - /* same typedef as in ngage SDKs e32def.h */ - typedef signed int TInt; - /* TODO: if it turns out that this only works when built as C++, - move SDL_PLATFORM_NGAGE into the C++ section in SDL_main.h */ - TInt E32Main() - { - return SDL_RunApp(0, NULL, SDL_main, NULL); - } - - /* end of SDL_PLATFORM_NGAGE impl */ + /* end of SDL_PLATFORM_WINDOWS impls */ #else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */ int main(int argc, char *argv[]) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h index c626b22..365ae36 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_messagebox.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryMessagebox * - * Message box support routines. + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. */ #ifndef SDL_messagebox_h_ @@ -39,11 +50,11 @@ extern "C" { #endif /** - * SDL_MessageBox flags. + * Message box flags. * * If supported will display warning icon, etc. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxFlags; @@ -56,7 +67,7 @@ typedef Uint32 SDL_MessageBoxFlags; /** * SDL_MessageBoxButtonData flags. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MessageBoxButtonFlags; @@ -66,7 +77,7 @@ typedef Uint32 SDL_MessageBoxButtonFlags; /** * Individual button data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxButtonData { @@ -78,7 +89,7 @@ typedef struct SDL_MessageBoxButtonData /** * RGB value used in a message box color scheme * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColor { @@ -96,23 +107,23 @@ typedef enum SDL_MessageBoxColorType SDL_MESSAGEBOX_COLOR_BUTTON_BORDER, SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND, SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED, - SDL_MESSAGEBOX_COLOR_MAX /**< Size of the colors array of SDL_MessageBoxColorScheme. */ + SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */ } SDL_MessageBoxColorType; /** * A set of colors to use for message box dialogs * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxColorScheme { - SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; + SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]; } SDL_MessageBoxColorScheme; /** * MessageBox structure containing title, text, window, etc. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_MessageBoxData { @@ -154,14 +165,14 @@ typedef struct SDL_MessageBoxData * other options. * \param buttonid the pointer to which user id of hit button should be * copied. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowSimpleMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid); /** * Display a simple modal message box. @@ -193,17 +204,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData * to stderr if you can. * * \param flags an SDL_MessageBoxFlags value. - * \param title uTF-8 title text. - * \param message uTF-8 message text. + * \param title UTF-8 title text. + * \param message UTF-8 message text. * \param window the parent window, or NULL for no parent. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowMessageBox */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h index 7c9aece..14b1bc8 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_metal.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,10 @@ * # CategoryMetal * * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. */ #ifndef SDL_metal_h_ @@ -39,7 +43,7 @@ extern "C" { /** * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_MetalView; @@ -61,7 +65,7 @@ typedef void *SDL_MetalView; * \param window the window. * \returns handle NSView or UIView. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_DestroyView * \sa SDL_Metal_GetLayer @@ -76,7 +80,7 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *windo * * \param view the SDL_MetalView object. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Metal_CreateView */ @@ -88,7 +92,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view); * \param view the SDL_MetalView object. * \returns a pointer. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h index 23317e0..3dd6fcd 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_misc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -62,12 +62,12 @@ extern "C" { * * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for * local files, if supported. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_OpenURL(const char *url); +extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h index 90c8560..18856e2 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mouse.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,36 @@ /** * # CategoryMouse * - * SDL mouse handling. + * Any GUI application has to deal with the mouse, and SDL provides functions + * to manage mouse input and the displayed cursor. + * + * Most interactions with the mouse will come through the event subsystem. + * Moving a mouse generates an SDL_EVENT_MOUSE_MOTION event, pushing a button + * generates SDL_EVENT_MOUSE_BUTTON_DOWN, etc, but one can also query the + * current state of the mouse at any time with SDL_GetMouseState(). + * + * For certain games, it's useful to disassociate the mouse cursor from mouse + * input. An FPS, for example, would not want the player's motion to stop as + * the mouse hits the edge of the window. For these scenarios, use + * SDL_SetWindowRelativeMouseMode(), which hides the cursor, grabs mouse input + * to the window, and reads mouse input no matter how far it moves. + * + * Games that want the system to track the mouse but want to draw their own + * cursor can use SDL_HideCursor() and SDL_ShowCursor(). It might be more + * efficient to let the system manage the cursor, if possible, using + * SDL_SetCursor() with a custom image made through SDL_CreateColorCursor(), + * or perhaps just a specific system cursor from SDL_CreateSystemCursor(). + * + * SDL can, on many platforms, differentiate between multiple connected mice, + * allowing for interesting input scenarios and multiplayer games. They can be + * enumerated with SDL_GetMice(), and SDL will send SDL_EVENT_MOUSE_ADDED and + * SDL_EVENT_MOUSE_REMOVED events as they are connected and unplugged. + * + * Since many apps only care about basic mouse input, SDL offers a virtual + * mouse device for touch and pen input, which often can make a desktop + * application work on a touchscreen phone without any code changes. Apps that + * care about touch/pen separately from mouse input should filter out events + * with a `which` field of SDL_TOUCH_MOUSEID/SDL_PEN_MOUSEID. */ #ifndef SDL_mouse_h_ @@ -30,6 +59,7 @@ #include #include +#include #include #include @@ -46,7 +76,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_MouseID; @@ -55,14 +85,14 @@ typedef Uint32 SDL_MouseID; * * This is opaque data. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Cursor SDL_Cursor; /** * Cursor types for SDL_CreateSystemCursor(). * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemCursor { @@ -86,13 +116,13 @@ typedef enum SDL_SystemCursor SDL_SYSTEM_CURSOR_S_RESIZE, /**< Window resize bottom. May be NS_RESIZE. */ SDL_SYSTEM_CURSOR_SW_RESIZE, /**< Window resize bottom-left. May be NESW_RESIZE. */ SDL_SYSTEM_CURSOR_W_RESIZE, /**< Window resize left. May be EW_RESIZE. */ - SDL_NUM_SYSTEM_CURSORS + SDL_SYSTEM_CURSOR_COUNT } SDL_SystemCursor; /** * Scroll direction types for the Scroll event * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MouseWheelDirection { @@ -109,7 +139,7 @@ typedef enum SDL_MouseWheelDirection * - Button 4: Side mouse button 1 * - Button 5: Side mouse button 2 * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetMouseState * \sa SDL_GetGlobalMouseState @@ -123,12 +153,12 @@ typedef Uint32 SDL_MouseButtonFlags; #define SDL_BUTTON_X1 4 #define SDL_BUTTON_X2 5 -#define SDL_BUTTON(X) (1u << ((X)-1)) -#define SDL_BUTTON_LMASK SDL_BUTTON(SDL_BUTTON_LEFT) -#define SDL_BUTTON_MMASK SDL_BUTTON(SDL_BUTTON_MIDDLE) -#define SDL_BUTTON_RMASK SDL_BUTTON(SDL_BUTTON_RIGHT) -#define SDL_BUTTON_X1MASK SDL_BUTTON(SDL_BUTTON_X1) -#define SDL_BUTTON_X2MASK SDL_BUTTON(SDL_BUTTON_X2) +#define SDL_BUTTON_MASK(X) (1u << ((X)-1)) +#define SDL_BUTTON_LMASK SDL_BUTTON_MASK(SDL_BUTTON_LEFT) +#define SDL_BUTTON_MMASK SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE) +#define SDL_BUTTON_RMASK SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) +#define SDL_BUTTON_X1MASK SDL_BUTTON_MASK(SDL_BUTTON_X1) +#define SDL_BUTTON_X2MASK SDL_BUTTON_MASK(SDL_BUTTON_X2) /* Function prototypes */ @@ -136,13 +166,15 @@ typedef Uint32 SDL_MouseButtonFlags; /** * Return whether a mouse is currently connected. * - * \returns SDL_TRUE if a mouse is connected, SDL_FALSE otherwise. + * \returns true if a mouse is connected, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HasMouse(void); /** * Get a list of currently connected mice. @@ -158,7 +190,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseNameForID * \sa SDL_HasMouse @@ -174,7 +208,9 @@ extern SDL_DECLSPEC SDL_MouseID * SDLCALL SDL_GetMice(int *count); * \returns the name of the selected mouse, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMice */ @@ -185,26 +221,39 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID insta * * \returns the window with mouse focus. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); /** - * Retrieve the current state of the mouse. + * Query SDL's cache for the synchronous mouse button state and the + * window-relative SDL-cursor position. * - * The current button state is returned as a button bitmask, which can be - * tested using the SDL_BUTTON(X) macro (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse cursor position relative to the focus window. You can pass NULL for - * either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x the x coordinate of the mouse cursor position relative to the - * focus window. - * \param y the y coordinate of the mouse cursor position relative to the - * focus window. - * \returns a 32-bit button bitmask of the current button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the focused window. + * + * In Relative Mode, the SDL-cursor's position usually contradicts the + * platform-cursor's position as manually calculated from + * SDL_GetGlobalMouseState() and SDL_GetWindowPosition. + * + * \param x a pointer to receive the SDL-cursor's x-position from the focused + * window's top left corner, can be NULL if unused. + * \param y a pointer to receive the SDL-cursor's y-position from the focused + * window's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState * \sa SDL_GetRelativeMouseState @@ -212,51 +261,74 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void); extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetMouseState(float *x, float *y); /** - * Get the current state of the mouse in relation to the desktop. + * Query the platform for the asynchronous mouse button state and the + * desktop-relative platform-cursor position. * - * This works similarly to SDL_GetMouseState(), but the coordinates will be - * reported relative to the top-left of the desktop. This can be useful if you - * need to track the mouse outside of a specific window and SDL_CaptureMouse() - * doesn't fit your needs. For example, it could be useful if you need to - * track the mouse while dragging a window, where coordinates relative to a - * window might not be in sync at all times. + * This function immediately queries the platform for the most recent + * asynchronous state, more costly than retrieving SDL's cached state in + * SDL_GetMouseState(). * - * Note: SDL_GetMouseState() returns the mouse position as SDL understands it - * from the last pump of the event queue. This function, however, queries the - * OS for the current mouse position, and as such, might be a slightly less - * efficient function. Unless you know what you're doing and have a good - * reason to use this function, you probably want SDL_GetMouseState() instead. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y coordinates relative to the desktop. * - * \param x filled in with the current X coord relative to the desktop; can be - * NULL. - * \param y filled in with the current Y coord relative to the desktop; can be - * NULL. - * \returns the current button state as a bitmask which can be tested using - * the SDL_BUTTON(X) macros. + * In Relative Mode, the platform-cursor's position usually contradicts the + * SDL-cursor's position as manually calculated from SDL_GetMouseState() and + * SDL_GetWindowPosition. * - * \since This function is available since SDL 3.0.0. + * This function can be useful if you need to track the mouse outside of a + * specific window and SDL_CaptureMouse() doesn't fit your needs. For example, + * it could be useful if you need to track the mouse while dragging a window, + * where coordinates relative to a window might not be in sync at all times. + * + * \param x a pointer to receive the platform-cursor's x-position from the + * desktop's top left corner, can be NULL if unused. + * \param y a pointer to receive the platform-cursor's y-position from the + * desktop's top left corner, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CaptureMouse * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetGlobalMouseState(float *x, float *y); /** - * Retrieve the relative state of the mouse. + * Query SDL's cache for the synchronous mouse button state and accumulated + * mouse delta since last call. * - * The current button state is returned as a button bitmask, which can be - * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the - * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the - * mouse deltas since the last call to SDL_GetRelativeMouseState() or since - * event initialization. You can pass NULL for either `x` or `y`. + * This function returns the cached synchronous state as SDL understands it + * from the last pump of the event queue. * - * \param x a pointer filled with the last recorded x coordinate of the mouse. - * \param y a pointer filled with the last recorded y coordinate of the mouse. - * \returns a 32-bit button bitmask of the relative button state. + * To query the platform for immediate asynchronous state, use + * SDL_GetGlobalMouseState. * - * \since This function is available since SDL 3.0.0. + * Passing non-NULL pointers to `x` or `y` will write the destination with + * respective x or y deltas accumulated since the last call to this function + * (or since event initialization). + * + * This function is useful for reducing overhead by processing relative mouse + * inputs in one go per-frame instead of individually per-event, at the + * expense of losing the order between events within the frame (e.g. quickly + * pressing and releasing a button within the same frame). + * + * \param x a pointer to receive the x mouse delta accumulated since last + * call, can be NULL if unused. + * \param y a pointer to receive the y mouse delta accumulated since last + * call, can be NULL if unused. + * \returns a 32-bit bitmask of the button state that can be bitwise-compared + * against the SDL_BUTTON_MASK(X) macro. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMouseState + * \sa SDL_GetGlobalMouseState */ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float *x, float *y); @@ -275,7 +347,9 @@ extern SDL_DECLSPEC SDL_MouseButtonFlags SDLCALL SDL_GetRelativeMouseState(float * \param x the x coordinate within the window. * \param y the y coordinate within the window. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseGlobal */ @@ -295,14 +369,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window, * * \param x the x coordinate. * \param y the y coordinate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_WarpMouseInWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_WarpMouseGlobal(float x, float y); /** * Set relative mouse mode for a window. @@ -312,31 +388,39 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WarpMouseGlobal(float x, float y); * report continuous relative mouse motion even if the mouse is at the edge of * the window. * + * If you'd like to keep the mouse position fixed while in relative mode you + * can use SDL_SetWindowMouseRect(). If you'd like the cursor to be at a + * specific location when relative mode ends, you should use + * SDL_WarpMouseInWindow() before disabling relative mode. + * * This function will flush any pending mouse motion for this window. * * \param window the window to change. - * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable relative mode, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowRelativeMouseMode(SDL_Window *window, bool enabled); /** * Query whether relative mouse mode is enabled for a window. * * \param window the window to query. - * \returns SDL_TRUE if relative mode is enabled for a window or SDL_FALSE - * otherwise. + * \returns true if relative mode is enabled for a window or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowRelativeMouseMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window *window); /** * Capture the mouse and to track input outside an SDL window. @@ -374,15 +458,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowRelativeMouseMode(SDL_Window * * app, you can disable auto capture by setting the * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero. * - * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable capturing, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetGlobalMouseState */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled); /** * Create a cursor using the specified bitmap data and mask (in MSB format). @@ -419,7 +505,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CaptureMouse(SDL_bool enabled); * \returns a new cursor with the specified parameters on success or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateSystemCursor @@ -450,7 +538,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 * data, * \returns the new cursor on success or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCursor * \sa SDL_CreateSystemCursor @@ -468,7 +558,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf * \returns a cursor on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyCursor */ @@ -483,14 +575,16 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor * this is desired for any reason. * * \param cursor a cursor to make active. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); /** * Get the active cursor. @@ -500,7 +594,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetCursor(SDL_Cursor *cursor); * * \returns the active cursor or NULL if there is no mouse. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetCursor */ @@ -515,7 +611,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void); * \returns the default cursor on success or NULL on failuree; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); @@ -527,7 +625,9 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void); * * \param cursor the cursor to free. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateColorCursor * \sa SDL_CreateCursor @@ -538,41 +638,47 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCursor(SDL_Cursor *cursor); /** * Show the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_HideCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowCursor(void); /** * Hide the cursor. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CursorVisible * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideCursor(void); +extern SDL_DECLSPEC bool SDLCALL SDL_HideCursor(void); /** * Return whether the cursor is currently being shown. * - * \returns `SDL_TRUE` if the cursor is being shown, or `SDL_FALSE` if the - * cursor is hidden. + * \returns `true` if the cursor is being shown, or `false` if the cursor is + * hidden. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideCursor * \sa SDL_ShowCursor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); +extern SDL_DECLSPEC bool SDLCALL SDL_CursorVisible(void); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h index 3a7ce56..c88ec15 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_mutex.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,84 +25,245 @@ /** * # CategoryMutex * - * Functions to provide thread synchronization primitives. + * SDL offers several thread synchronization primitives. This document can't + * cover the complicated topic of thread safety, but reading up on what each + * of these primitives are, why they are useful, and how to correctly use them + * is vital to writing correct and safe multithreaded programs. + * + * - Mutexes: SDL_CreateMutex() + * - Read/Write locks: SDL_CreateRWLock() + * - Semaphores: SDL_CreateSemaphore() + * - Condition variables: SDL_CreateCondition() + * + * SDL also offers a datatype, SDL_InitState, which can be used to make sure + * only one thread initializes/deinitializes some resource that several + * threads might try to use for the first time simultaneously. */ #include +#include #include +#include -/******************************************************************************/ -/* Enable thread safety attributes only with clang. +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Enable thread safety attributes, only with clang. + * * The attributes can be safely erased when compiling with other compilers. * * To enable analysis, set these environment variables before running cmake: - * export CC=clang - * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` */ -#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ - defined(__clang__) && (!defined(SWIG)) +#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) + +#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG)) #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) #else #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ #endif +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SCOPED_CAPABILITY \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PT_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_BEFORE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRED_AFTER(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_REQUIRES_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ACQUIRE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RELEASE_GENERIC(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TRY_ACQUIRE_SHARED(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_EXCLUDES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ASSERT_SHARED_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_RETURN_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) @@ -130,7 +291,7 @@ extern "C" { * * https://en.wikipedia.org/wiki/Mutex * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Mutex SDL_Mutex; @@ -147,7 +308,7 @@ typedef struct SDL_Mutex SDL_Mutex; * \returns the initialized and unlocked mutex or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyMutex * \sa SDL_LockMutex @@ -173,7 +334,7 @@ extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); * * \param mutex the mutex to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockMutex * \sa SDL_UnlockMutex @@ -184,22 +345,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * Try to lock a mutex without blocking. * * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns SDL_FALSE immediately. + * this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. * - * This function returns SDL_TRUE if passed a NULL mutex. + * This function returns true if passed a NULL mutex. * * \param mutex the mutex to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the mutex would block. + * \returns true on success, false if the mutex would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_UnlockMutex */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0, mutex); /** * Unlock the mutex. @@ -213,7 +374,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ * * \param mutex the mutex to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex * \sa SDL_TryLockMutex @@ -231,7 +392,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m * * \param mutex the mutex to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateMutex */ @@ -261,7 +422,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); * about how threads are scheduled and when they can be recursively locked. * These are documented in the other rwlock functions. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_RWLock SDL_RWLock; @@ -296,7 +457,7 @@ typedef struct SDL_RWLock SDL_RWLock; * \returns the initialized and unlocked read/write lock or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRWLock * \sa SDL_LockRWLockForReading @@ -336,7 +497,7 @@ extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading @@ -367,7 +528,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD * * \param rwlock the read/write lock to lock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting @@ -379,7 +540,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Try to lock a read/write lock _for reading_ without blocking. * * This works just like SDL_LockRWLockForReading(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need access to a resource but don't want to * wait for it, and will return to it to try again later. @@ -387,24 +548,24 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * Trying to lock for read-only access can succeed if other threads are * holding read-only locks, as this won't prevent access. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_TryLockRWLockForWriting * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE_SHARED(0, rwlock); /** * Try to lock a read/write lock _for writing_ without blocking. * * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not - * available, then this function returns SDL_FALSE immediately. + * available, then this function returns false immediately. * * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. @@ -417,18 +578,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwl * read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock before requesting a write lock. * - * This function returns SDL_TRUE if passed a NULL rwlock. + * This function returns true if passed a NULL rwlock. * * \param rwlock the rwlock to try to lock. - * \returns SDL_TRUE on success, SDL_FALSE if the lock would block. + * \returns true on success, false if the lock would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting * \sa SDL_TryLockRWLockForReading * \sa SDL_UnlockRWLock */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); +extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_TRY_ACQUIRE(0, rwlock); /** * Unlock the read/write lock. @@ -446,7 +607,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwl * * \param rwlock the rwlock to unlock. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading * \sa SDL_LockRWLockForWriting @@ -466,7 +627,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS * * \param rwlock the rwlock to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRWLock */ @@ -492,7 +653,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); * * https://en.wikipedia.org/wiki/Semaphore_(programming) * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Semaphore SDL_Semaphore; @@ -509,7 +670,7 @@ typedef struct SDL_Semaphore SDL_Semaphore; * \returns a new semaphore or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySemaphore * \sa SDL_SignalSemaphore @@ -528,7 +689,7 @@ extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_v * * \param sem the semaphore to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSemaphore */ @@ -546,7 +707,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * * \param sem the semaphore wait on. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore @@ -560,18 +721,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * This function checks to see if the semaphore pointed to by `sem` has a * positive value and atomically decrements the semaphore value if it does. If * the semaphore doesn't have a positive value, the function immediately - * returns SDL_FALSE. + * returns false. * * \param sem the semaphore to wait on. - * \returns SDL_TRUE if the wait succeeds, SDL_FALSE if the wait would block. + * \returns true if the wait succeeds, false if the wait would block. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_WaitSemaphore * \sa SDL_WaitSemaphoreTimeout */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); +extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); /** * Wait until a semaphore has a positive value and then decrements it. @@ -583,22 +744,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to wait on. * \param timeoutMS the length of the timeout, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the wait succeeds or SDL_FALSE if the wait times out. + * \returns true if the wait succeeds or false if the wait times out. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); +extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Sint32 timeoutMS); /** * Atomically increment a semaphore's value and wake waiting threads. * * \param sem the semaphore to increment. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_TryWaitSemaphore * \sa SDL_WaitSemaphore @@ -612,7 +773,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to query. * \returns the current value of the semaphore. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); @@ -635,7 +796,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); * * https://en.wikipedia.org/wiki/Condition_variable * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Condition SDL_Condition; @@ -645,7 +806,7 @@ typedef struct SDL_Condition SDL_Condition; * \returns a new condition variable or NULL on failure; call SDL_GetError() * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -660,7 +821,7 @@ extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); * * \param cond the condition variable to destroy. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCondition */ @@ -673,7 +834,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_WaitCondition @@ -688,7 +849,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalCondition * \sa SDL_WaitCondition @@ -716,7 +877,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_BroadcastCondition(SDL_Condition *cond); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition @@ -741,22 +902,167 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mute * \param mutex the mutex used to coordinate thread access. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. - * \returns SDL_TRUE if the condition variable is signaled, SDL_FALSE if the - * condition is not signaled in the allotted time. + * \returns true if the condition variable is signaled, false if the condition + * is not signaled in the allotted time. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BroadcastCondition * \sa SDL_SignalCondition * \sa SDL_WaitCondition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, +extern SDL_DECLSPEC bool SDLCALL SDL_WaitConditionTimeout(SDL_Condition *cond, SDL_Mutex *mutex, Sint32 timeoutMS); /* @} *//* Condition variable functions */ +/** + * \name Thread-safe initialization state functions + */ +/* @{ */ + +/** + * The current status of an SDL_InitState structure. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_InitStatus +{ + SDL_INIT_STATUS_UNINITIALIZED, + SDL_INIT_STATUS_INITIALIZING, + SDL_INIT_STATUS_INITIALIZED, + SDL_INIT_STATUS_UNINITIALIZING +} SDL_InitStatus; + +/** + * A structure used for thread-safe initialization and shutdown. + * + * Here is an example of using this: + * + * ```c + * static SDL_AtomicInitState init; + * + * bool InitSystem(void) + * { + * if (!SDL_ShouldInit(&init)) { + * // The system is initialized + * return true; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * bool initialized = DoInitTasks(); + * SDL_SetInitialized(&init, initialized); + * return initialized; + * } + * + * bool UseSubsystem(void) + * { + * if (SDL_ShouldInit(&init)) { + * // Error, the subsystem isn't initialized + * SDL_SetInitialized(&init, false); + * return false; + * } + * + * // Do work using the initialized subsystem + * + * return true; + * } + * + * void QuitSystem(void) + * { + * if (!SDL_ShouldQuit(&init)) { + * // The system is not initialized + * return; + * } + * + * // At this point, you should not leave this function without calling SDL_SetInitialized() + * + * DoQuitTasks(); + * SDL_SetInitialized(&init, false); + * } + * ``` + * + * Note that this doesn't protect any resources created during initialization, + * or guarantee that nobody is using those resources during cleanup. You + * should use other mechanisms to protect those, if that's a concern for your + * code. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_InitState +{ + SDL_AtomicInt status; + SDL_ThreadID thread; + void *reserved; +} SDL_InitState; + +/** + * Return whether initialization should be done. + * + * This function checks the passed in state and if initialization should be + * done, sets the status to `SDL_INIT_STATUS_INITIALIZING` and returns true. + * If another thread is already modifying this state, it will wait until + * that's done before returning. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the initialization. + * + * \param state the initialization state to check. + * \returns true if initialization needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldInit(SDL_InitState *state); + +/** + * Return whether cleanup should be done. + * + * This function checks the passed in state and if cleanup should be done, + * sets the status to `SDL_INIT_STATUS_UNINITIALIZING` and returns true. + * + * If this function returns true, the calling code must call + * SDL_SetInitialized() to complete the cleanup. + * + * \param state the initialization state to check. + * \returns true if cleanup needs to be done, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetInitialized + * \sa SDL_ShouldInit + */ +extern SDL_DECLSPEC bool SDLCALL SDL_ShouldQuit(SDL_InitState *state); + +/** + * Finish an initialization state transition. + * + * This function sets the status of the passed in state to + * `SDL_INIT_STATUS_INITIALIZED` or `SDL_INIT_STATUS_UNINITIALIZED` and allows + * any threads waiting for the status to proceed. + * + * \param state the initialization state to check. + * \param initialized the new initialization state. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShouldInit + * \sa SDL_ShouldQuit + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetInitialized(SDL_InitState *state, bool initialized); + +/* @} *//* Thread-safe initialization state functions */ /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h index 02c881c..c93607e 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_oldnames.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -38,11 +38,14 @@ #ifdef SDL_ENABLE_OLD_NAMES /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_GetAtomicPointer #define SDL_AtomicLock SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_UnlockSpinlock #define SDL_atomic_t SDL_AtomicInt @@ -74,6 +77,7 @@ #define SDL_NewAudioStream SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -166,14 +170,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -193,7 +196,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -304,6 +307,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -419,9 +424,15 @@ #define SDL_LogSetAllPriority SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_MASK #define SDL_FreeCursor SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_TEXT @@ -558,6 +569,7 @@ #define SDL_WriteLE64 SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -580,7 +592,12 @@ #define SDL_SensorUpdate SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE false #define SDL_TABLESIZE SDL_arraysize +#define SDL_TRUE true +#define SDL_bool bool +#define SDL_size_add_overflow SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtok_r /* ##SDL_surface.h */ @@ -623,14 +640,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_SetiOSAnimationCallback #define SDL_iPhoneSetEventPump SDL_SetiOSEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_CleanupTLS #define SDL_TLSGet SDL_GetTLS #define SDL_TLSSet SDL_SetTLS @@ -645,6 +661,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint @@ -661,11 +681,14 @@ #elif !defined(SDL_DISABLE_OLD_NAMES) /* ##SDL_atomic.h */ -#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_AtomicCompareAndSwap -#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_AtomicCompareAndSwapPointer -#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_AtomicGetPointer +#define SDL_AtomicAdd SDL_AtomicAdd_renamed_SDL_AddAtomicInt +#define SDL_AtomicCAS SDL_AtomicCAS_renamed_SDL_CompareAndSwapAtomicInt +#define SDL_AtomicCASPtr SDL_AtomicCASPtr_renamed_SDL_CompareAndSwapAtomicPointer +#define SDL_AtomicGet SDL_AtomicGet_renamed_SDL_GetAtomicInt +#define SDL_AtomicGetPtr SDL_AtomicGetPtr_renamed_SDL_GetAtomicPointer #define SDL_AtomicLock SDL_AtomicLock_renamed_SDL_LockSpinlock -#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_AtomicSetPointer +#define SDL_AtomicSet SDL_AtomicSet_renamed_SDL_SetAtomicInt +#define SDL_AtomicSetPtr SDL_AtomicSetPtr_renamed_SDL_SetAtomicPointer #define SDL_AtomicTryLock SDL_AtomicTryLock_renamed_SDL_TryLockSpinlock #define SDL_AtomicUnlock SDL_AtomicUnlock_renamed_SDL_UnlockSpinlock #define SDL_atomic_t SDL_atomic_t_renamed_SDL_AtomicInt @@ -697,6 +720,7 @@ #define SDL_NewAudioStream SDL_NewAudioStream_renamed_SDL_CreateAudioStream /* ##SDL_cpuinfo.h */ +#define SDL_GetCPUCount SDL_GetCPUCount_renamed_SDL_GetNumLogicalCPUCores #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_renamed_SDL_GetSIMDAlignment /* ##SDL_endian.h */ @@ -789,14 +813,13 @@ #define SDL_WINDOWEVENT_RESTORED SDL_WINDOWEVENT_RESTORED_renamed_SDL_EVENT_WINDOW_RESTORED #define SDL_WINDOWEVENT_SHOWN SDL_WINDOWEVENT_SHOWN_renamed_SDL_EVENT_WINDOW_SHOWN #define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED -#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_WINDOWEVENT_TAKE_FOCUS_renamed_SDL_EVENT_WINDOW_TAKE_FOCUS #define SDL_eventaction SDL_eventaction_renamed_SDL_EventAction /* ##SDL_gamecontroller.h */ #define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID #define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX #define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY -#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_MAX +#define SDL_CONTROLLER_AXIS_MAX SDL_CONTROLLER_AXIS_MAX_renamed_SDL_GAMEPAD_AXIS_COUNT #define SDL_CONTROLLER_AXIS_RIGHTX SDL_CONTROLLER_AXIS_RIGHTX_renamed_SDL_GAMEPAD_AXIS_RIGHTX #define SDL_CONTROLLER_AXIS_RIGHTY SDL_CONTROLLER_AXIS_RIGHTY_renamed_SDL_GAMEPAD_AXIS_RIGHTY #define SDL_CONTROLLER_AXIS_TRIGGERLEFT SDL_CONTROLLER_AXIS_TRIGGERLEFT_renamed_SDL_GAMEPAD_AXIS_LEFT_TRIGGER @@ -816,7 +839,7 @@ #define SDL_CONTROLLER_BUTTON_INVALID SDL_CONTROLLER_BUTTON_INVALID_renamed_SDL_GAMEPAD_BUTTON_INVALID #define SDL_CONTROLLER_BUTTON_LEFTSHOULDER SDL_CONTROLLER_BUTTON_LEFTSHOULDER_renamed_SDL_GAMEPAD_BUTTON_LEFT_SHOULDER #define SDL_CONTROLLER_BUTTON_LEFTSTICK SDL_CONTROLLER_BUTTON_LEFTSTICK_renamed_SDL_GAMEPAD_BUTTON_LEFT_STICK -#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_MAX +#define SDL_CONTROLLER_BUTTON_MAX SDL_CONTROLLER_BUTTON_MAX_renamed_SDL_GAMEPAD_BUTTON_COUNT #define SDL_CONTROLLER_BUTTON_MISC1 SDL_CONTROLLER_BUTTON_MISC1_renamed_SDL_GAMEPAD_BUTTON_MISC1 #define SDL_CONTROLLER_BUTTON_PADDLE1 SDL_CONTROLLER_BUTTON_PADDLE1_renamed_SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 #define SDL_CONTROLLER_BUTTON_PADDLE2 SDL_CONTROLLER_BUTTON_PADDLE2_renamed_SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 @@ -928,6 +951,8 @@ #define SDL_HINT_DIRECTINPUT_ENABLED SDL_HINT_DIRECTINPUT_ENABLED_renamed_SDL_HINT_JOYSTICK_DIRECTINPUT #define SDL_HINT_GDK_TEXTINPUT_DEFAULT SDL_HINT_GDK_TEXTINPUT_DEFAULT_renamed_SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT #define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE_renamed_SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE +#define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS +#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE_renamed_SDL_HINT_JOYSTICK_ENHANCED_REPORTS #define SDL_HINT_LINUX_DIGITAL_HATS SDL_HINT_LINUX_DIGITAL_HATS_renamed_SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS #define SDL_HINT_LINUX_HAT_DEADZONES SDL_HINT_LINUX_HAT_DEADZONES_renamed_SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES #define SDL_HINT_LINUX_JOYSTICK_CLASSIC SDL_HINT_LINUX_JOYSTICK_CLASSIC_renamed_SDL_HINT_JOYSTICK_LINUX_CLASSIC @@ -1043,9 +1068,15 @@ #define SDL_LogSetAllPriority SDL_LogSetAllPriority_renamed_SDL_SetLogPriorities #define SDL_LogSetOutputFunction SDL_LogSetOutputFunction_renamed_SDL_SetLogOutputFunction #define SDL_LogSetPriority SDL_LogSetPriority_renamed_SDL_SetLogPriority +#define SDL_NUM_LOG_PRIORITIES SDL_NUM_LOG_PRIORITIES_renamed_SDL_LOG_PRIORITY_COUNT + +/* ##SDL_messagebox.h */ +#define SDL_MESSAGEBOX_COLOR_MAX SDL_MESSAGEBOX_COLOR_MAX_renamed_SDL_MESSAGEBOX_COLOR_COUNT /* ##SDL_mouse.h */ +#define SDL_BUTTON SDL_BUTTON_renamed_SDL_BUTTON_MASK #define SDL_FreeCursor SDL_FreeCursor_renamed_SDL_DestroyCursor +#define SDL_NUM_SYSTEM_CURSORS SDL_NUM_SYSTEM_CURSORS_renamed_SDL_SYSTEM_CURSOR_COUNT #define SDL_SYSTEM_CURSOR_ARROW SDL_SYSTEM_CURSOR_ARROW_renamed_SDL_SYSTEM_CURSOR_DEFAULT #define SDL_SYSTEM_CURSOR_HAND SDL_SYSTEM_CURSOR_HAND_renamed_SDL_SYSTEM_CURSOR_POINTER #define SDL_SYSTEM_CURSOR_IBEAM SDL_SYSTEM_CURSOR_IBEAM_renamed_SDL_SYSTEM_CURSOR_TEXT @@ -1182,6 +1213,7 @@ #define SDL_WriteLE64 SDL_WriteLE64_renamed_SDL_WriteU64LE /* ##SDL_scancode.h */ +#define SDL_NUM_SCANCODES SDL_NUM_SCANCODES_renamed_SDL_SCANCODE_COUNT #define SDL_SCANCODE_AUDIOFASTFORWARD SDL_SCANCODE_AUDIOFASTFORWARD_renamed_SDL_SCANCODE_MEDIA_FAST_FORWARD #define SDL_SCANCODE_AUDIOMUTE SDL_SCANCODE_AUDIOMUTE_renamed_SDL_SCANCODE_MUTE #define SDL_SCANCODE_AUDIONEXT SDL_SCANCODE_AUDIONEXT_renamed_SDL_SCANCODE_MEDIA_NEXT_TRACK @@ -1204,7 +1236,12 @@ #define SDL_SensorUpdate SDL_SensorUpdate_renamed_SDL_UpdateSensors /* ##SDL_stdinc.h */ +#define SDL_FALSE SDL_FALSE_renamed_false #define SDL_TABLESIZE SDL_TABLESIZE_renamed_SDL_arraysize +#define SDL_TRUE SDL_TRUE_renamed_true +#define SDL_bool SDL_bool_renamed_bool +#define SDL_size_add_overflow SDL_size_add_overflow_renamed_SDL_size_add_check_overflow +#define SDL_size_mul_overflow SDL_size_mul_overflow_renamed_SDL_size_mul_check_overflow #define SDL_strtokr SDL_strtokr_renamed_SDL_strtok_r /* ##SDL_surface.h */ @@ -1247,14 +1284,13 @@ #define SDL_LinuxSetThreadPriorityAndPolicy SDL_LinuxSetThreadPriorityAndPolicy_renamed_SDL_SetLinuxThreadPriorityAndPolicy #define SDL_OnApplicationDidBecomeActive SDL_OnApplicationDidBecomeActive_renamed_SDL_OnApplicationDidEnterForeground #define SDL_OnApplicationWillResignActive SDL_OnApplicationWillResignActive_renamed_SDL_OnApplicationWillEnterBackground -#define SDL_WinRTGetDeviceFamily SDL_WinRTGetDeviceFamily_renamed_SDL_GetWinRTDeviceFamily -#define SDL_GetWinRTFSPathUTF8 SDL_GetWinRTFSPathUTF8_renamed_SDL_GetWinRTFSPath #define SDL_iOSSetAnimationCallback SDL_iOSSetAnimationCallback_renamed_SDL_SetiOSAnimationCallback #define SDL_iOSSetEventPump SDL_iOSSetEventPump_renamed_SDL_SetiOSEventPump #define SDL_iPhoneSetAnimationCallback SDL_iPhoneSetAnimationCallback_renamed_SDL_iOSSetAnimationCallback #define SDL_iPhoneSetEventPump SDL_iPhoneSetEventPump_renamed_SDL_iOSSetEventPump /* ##SDL_thread.h */ +#define SDL_SetThreadPriority SDL_SetThreadPriority_renamed_SDL_SetCurrentThreadPriority #define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS #define SDL_TLSGet SDL_TLSGet_renamed_SDL_GetTLS #define SDL_TLSSet SDL_TLSSet_renamed_SDL_SetTLS @@ -1269,6 +1305,10 @@ /* ##SDL_video.h */ #define SDL_GL_DeleteContext SDL_GL_DeleteContext_renamed_SDL_GL_DestroyContext +#define SDL_GLattr SDL_GLattr_renamed_SDL_GLAttr +#define SDL_GLcontextFlag SDL_GLcontextFlag_renamed_SDL_GLContextFlag +#define SDL_GLcontextReleaseFlag SDL_GLcontextReleaseFlag_renamed_SDL_GLContextReleaseFlag +#define SDL_GLprofile SDL_GLprofile_renamed_SDL_GLProfile #define SDL_GetClosestDisplayMode SDL_GetClosestDisplayMode_renamed_SDL_GetClosestFullscreenDisplayMode #define SDL_GetDisplayOrientation SDL_GetDisplayOrientation_renamed_SDL_GetCurrentDisplayOrientation #define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h index 6bdcbe0..d1b8b02 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengl.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -783,6 +783,7 @@ typedef double GLclampd; /* double precision float in [0,1] */ * Miscellaneous */ +#ifndef SDL_OPENGL_1_NO_PROTOTYPES GLAPI void GLAPIENTRY glClearIndex( GLfloat c ); GLAPI void GLAPIENTRY glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); @@ -1480,6 +1481,706 @@ GLAPI void GLAPIENTRY glPushName( GLuint name ); GLAPI void GLAPIENTRY glPopName( void ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCLEARINDEXPROC) ( GLfloat c ); + +typedef void (APIENTRYP PFNGLCLEARCOLORPROC) ( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLCLEARPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLINDEXMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLCOLORMASKPROC) ( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha ); + +typedef void (APIENTRYP PFNGLALPHAFUNCPROC) ( GLenum func, GLclampf ref ); + +typedef void (APIENTRYP PFNGLBLENDFUNCPROC) ( GLenum sfactor, GLenum dfactor ); + +typedef void (APIENTRYP PFNGLLOGICOPPROC) ( GLenum opcode ); + +typedef void (APIENTRYP PFNGLCULLFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLFRONTFACEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLPOINTSIZEPROC) ( GLfloat size ); + +typedef void (APIENTRYP PFNGLLINEWIDTHPROC) ( GLfloat width ); + +typedef void (APIENTRYP PFNGLLINESTIPPLEPROC) ( GLint factor, GLushort pattern ); + +typedef void (APIENTRYP PFNGLPOLYGONMODEPROC) ( GLenum face, GLenum mode ); + +typedef void (APIENTRYP PFNGLPOLYGONOFFSETPROC) ( GLfloat factor, GLfloat units ); + +typedef void (APIENTRYP PFNGLPOLYGONSTIPPLEPROC) ( const GLubyte *mask ); + +typedef void (APIENTRYP PFNGLGETPOLYGONSTIPPLEPROC) ( GLubyte *mask ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLEDGEFLAGVPROC) ( const GLboolean *flag ); + +typedef void (APIENTRYP PFNGLSCISSORPROC) ( GLint x, GLint y, GLsizei width, GLsizei height); + +typedef void (APIENTRYP PFNGLCLIPPLANEPROC) ( GLenum plane, const GLdouble *equation ); + +typedef void (APIENTRYP PFNGLGETCLIPPLANEPROC) ( GLenum plane, GLdouble *equation ); + +typedef void (APIENTRYP PFNGLDRAWBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLREADBUFFERPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENABLEPROC) ( GLenum cap ); + +typedef void (APIENTRYP PFNGLDISABLEPROC) ( GLenum cap ); + +typedef GLboolean (APIENTRYP PFNGLISENABLEDPROC) ( GLenum cap ); + + +typedef void (APIENTRYP PFNGLENABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLDISABLECLIENTSTATEPROC) ( GLenum cap ); /* 1.1 */ + + +typedef void (APIENTRYP PFNGLGETBOOLEANVPROC) ( GLenum pname, GLboolean *params ); + +typedef void (APIENTRYP PFNGLGETDOUBLEVPROC) ( GLenum pname, GLdouble *params ); + +typedef void (APIENTRYP PFNGLGETFLOATVPROC) ( GLenum pname, GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETINTEGERVPROC) ( GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLPUSHATTRIBPROC) ( GLbitfield mask ); + +typedef void (APIENTRYP PFNGLPOPATTRIBPROC) ( void ); + + +typedef void (APIENTRYP PFNGLPUSHCLIENTATTRIBPROC) ( GLbitfield mask ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLPOPCLIENTATTRIBPROC) ( void ); /* 1.1 */ + + +typedef GLint (APIENTRYP PFNGLRENDERMODEPROC) ( GLenum mode ); + +typedef GLenum (APIENTRYP PFNGLGETERRORPROC) ( void ); + +typedef const GLubyte * (APIENTRYP PFNGLGETSTRINGPROC) ( GLenum name ); + +typedef void (APIENTRYP PFNGLFINISHPROC) ( void ); + +typedef void (APIENTRYP PFNGLFLUSHPROC) ( void ); + +typedef void (APIENTRYP PFNGLHINTPROC) ( GLenum target, GLenum mode ); + + +/* + * Depth Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARDEPTHPROC) ( GLclampd depth ); + +typedef void (APIENTRYP PFNGLDEPTHFUNCPROC) ( GLenum func ); + +typedef void (APIENTRYP PFNGLDEPTHMASKPROC) ( GLboolean flag ); + +typedef void (APIENTRYP PFNGLDEPTHRANGEPROC) ( GLclampd near_val, GLclampd far_val ); + + +/* + * Accumulation Buffer + */ + +typedef void (APIENTRYP PFNGLCLEARACCUMPROC) ( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha ); + +typedef void (APIENTRYP PFNGLACCUMPROC) ( GLenum op, GLfloat value ); + + +/* + * Transformation + */ + +typedef void (APIENTRYP PFNGLMATRIXMODEPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLORTHOPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLFRUSTUMPROC) ( GLdouble left, GLdouble right, + GLdouble bottom, GLdouble top, + GLdouble near_val, GLdouble far_val ); + +typedef void (APIENTRYP PFNGLVIEWPORTPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height ); + +typedef void (APIENTRYP PFNGLPUSHMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLPOPMATRIXPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADIDENTITYPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLLOADMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLMULTMATRIXDPROC) ( const GLdouble *m ); +typedef void (APIENTRYP PFNGLMULTMATRIXFPROC) ( const GLfloat *m ); + +typedef void (APIENTRYP PFNGLROTATEDPROC) ( GLdouble angle, + GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLROTATEFPROC) ( GLfloat angle, + GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLSCALEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLSCALEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + +typedef void (APIENTRYP PFNGLTRANSLATEDPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLTRANSLATEFPROC) ( GLfloat x, GLfloat y, GLfloat z ); + + +/* + * Display Lists + */ + +typedef GLboolean (APIENTRYP PFNGLISLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLDELETELISTSPROC) ( GLuint list, GLsizei range ); + +typedef GLuint (APIENTRYP PFNGLGENLISTSPROC) ( GLsizei range ); + +typedef void (APIENTRYP PFNGLNEWLISTPROC) ( GLuint list, GLenum mode ); + +typedef void (APIENTRYP PFNGLENDLISTPROC) ( void ); + +typedef void (APIENTRYP PFNGLCALLLISTPROC) ( GLuint list ); + +typedef void (APIENTRYP PFNGLCALLLISTSPROC) ( GLsizei n, GLenum type, + const GLvoid *lists ); + +typedef void (APIENTRYP PFNGLLISTBASEPROC) ( GLuint base ); + + +/* + * Drawing Functions + */ + +typedef void (APIENTRYP PFNGLBEGINPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLENDPROC) ( void ); + + +typedef void (APIENTRYP PFNGLVERTEX2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLVERTEX2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLVERTEX2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLVERTEX2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLVERTEX3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLVERTEX3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLVERTEX3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLVERTEX3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLVERTEX4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLVERTEX4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLVERTEX4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLVERTEX4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLVERTEX2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLVERTEX4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLVERTEX4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLVERTEX4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLVERTEX4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLNORMAL3BPROC) ( GLbyte nx, GLbyte ny, GLbyte nz ); +typedef void (APIENTRYP PFNGLNORMAL3DPROC) ( GLdouble nx, GLdouble ny, GLdouble nz ); +typedef void (APIENTRYP PFNGLNORMAL3FPROC) ( GLfloat nx, GLfloat ny, GLfloat nz ); +typedef void (APIENTRYP PFNGLNORMAL3IPROC) ( GLint nx, GLint ny, GLint nz ); +typedef void (APIENTRYP PFNGLNORMAL3SPROC) ( GLshort nx, GLshort ny, GLshort nz ); + +typedef void (APIENTRYP PFNGLNORMAL3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLNORMAL3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLNORMAL3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLNORMAL3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLNORMAL3SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLINDEXDPROC) ( GLdouble c ); +typedef void (APIENTRYP PFNGLINDEXFPROC) ( GLfloat c ); +typedef void (APIENTRYP PFNGLINDEXIPROC) ( GLint c ); +typedef void (APIENTRYP PFNGLINDEXSPROC) ( GLshort c ); +typedef void (APIENTRYP PFNGLINDEXUBPROC) ( GLubyte c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLINDEXDVPROC) ( const GLdouble *c ); +typedef void (APIENTRYP PFNGLINDEXFVPROC) ( const GLfloat *c ); +typedef void (APIENTRYP PFNGLINDEXIVPROC) ( const GLint *c ); +typedef void (APIENTRYP PFNGLINDEXSVPROC) ( const GLshort *c ); +typedef void (APIENTRYP PFNGLINDEXUBVPROC) ( const GLubyte *c ); /* 1.1 */ + +typedef void (APIENTRYP PFNGLCOLOR3BPROC) ( GLbyte red, GLbyte green, GLbyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3DPROC) ( GLdouble red, GLdouble green, GLdouble blue ); +typedef void (APIENTRYP PFNGLCOLOR3FPROC) ( GLfloat red, GLfloat green, GLfloat blue ); +typedef void (APIENTRYP PFNGLCOLOR3IPROC) ( GLint red, GLint green, GLint blue ); +typedef void (APIENTRYP PFNGLCOLOR3SPROC) ( GLshort red, GLshort green, GLshort blue ); +typedef void (APIENTRYP PFNGLCOLOR3UBPROC) ( GLubyte red, GLubyte green, GLubyte blue ); +typedef void (APIENTRYP PFNGLCOLOR3UIPROC) ( GLuint red, GLuint green, GLuint blue ); +typedef void (APIENTRYP PFNGLCOLOR3USPROC) ( GLushort red, GLushort green, GLushort blue ); + +typedef void (APIENTRYP PFNGLCOLOR4BPROC) ( GLbyte red, GLbyte green, + GLbyte blue, GLbyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4DPROC) ( GLdouble red, GLdouble green, + GLdouble blue, GLdouble alpha ); +typedef void (APIENTRYP PFNGLCOLOR4FPROC) ( GLfloat red, GLfloat green, + GLfloat blue, GLfloat alpha ); +typedef void (APIENTRYP PFNGLCOLOR4IPROC) ( GLint red, GLint green, + GLint blue, GLint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4SPROC) ( GLshort red, GLshort green, + GLshort blue, GLshort alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UBPROC) ( GLubyte red, GLubyte green, + GLubyte blue, GLubyte alpha ); +typedef void (APIENTRYP PFNGLCOLOR4UIPROC) ( GLuint red, GLuint green, + GLuint blue, GLuint alpha ); +typedef void (APIENTRYP PFNGLCOLOR4USPROC) ( GLushort red, GLushort green, + GLushort blue, GLushort alpha ); + + +typedef void (APIENTRYP PFNGLCOLOR3BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR3SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR3UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR3UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR3USVPROC) ( const GLushort *v ); + +typedef void (APIENTRYP PFNGLCOLOR4BVPROC) ( const GLbyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLCOLOR4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLCOLOR4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLCOLOR4SVPROC) ( const GLshort *v ); +typedef void (APIENTRYP PFNGLCOLOR4UBVPROC) ( const GLubyte *v ); +typedef void (APIENTRYP PFNGLCOLOR4UIVPROC) ( const GLuint *v ); +typedef void (APIENTRYP PFNGLCOLOR4USVPROC) ( const GLushort *v ); + + +typedef void (APIENTRYP PFNGLTEXCOORD1DPROC) ( GLdouble s ); +typedef void (APIENTRYP PFNGLTEXCOORD1FPROC) ( GLfloat s ); +typedef void (APIENTRYP PFNGLTEXCOORD1IPROC) ( GLint s ); +typedef void (APIENTRYP PFNGLTEXCOORD1SPROC) ( GLshort s ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DPROC) ( GLdouble s, GLdouble t ); +typedef void (APIENTRYP PFNGLTEXCOORD2FPROC) ( GLfloat s, GLfloat t ); +typedef void (APIENTRYP PFNGLTEXCOORD2IPROC) ( GLint s, GLint t ); +typedef void (APIENTRYP PFNGLTEXCOORD2SPROC) ( GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DPROC) ( GLdouble s, GLdouble t, GLdouble r ); +typedef void (APIENTRYP PFNGLTEXCOORD3FPROC) ( GLfloat s, GLfloat t, GLfloat r ); +typedef void (APIENTRYP PFNGLTEXCOORD3IPROC) ( GLint s, GLint t, GLint r ); +typedef void (APIENTRYP PFNGLTEXCOORD3SPROC) ( GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DPROC) ( GLdouble s, GLdouble t, GLdouble r, GLdouble q ); +typedef void (APIENTRYP PFNGLTEXCOORD4FPROC) ( GLfloat s, GLfloat t, GLfloat r, GLfloat q ); +typedef void (APIENTRYP PFNGLTEXCOORD4IPROC) ( GLint s, GLint t, GLint r, GLint q ); +typedef void (APIENTRYP PFNGLTEXCOORD4SPROC) ( GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLTEXCOORD1DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD1SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLTEXCOORD4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLTEXCOORD4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRASTERPOS2DPROC) ( GLdouble x, GLdouble y ); +typedef void (APIENTRYP PFNGLRASTERPOS2FPROC) ( GLfloat x, GLfloat y ); +typedef void (APIENTRYP PFNGLRASTERPOS2IPROC) ( GLint x, GLint y ); +typedef void (APIENTRYP PFNGLRASTERPOS2SPROC) ( GLshort x, GLshort y ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DPROC) ( GLdouble x, GLdouble y, GLdouble z ); +typedef void (APIENTRYP PFNGLRASTERPOS3FPROC) ( GLfloat x, GLfloat y, GLfloat z ); +typedef void (APIENTRYP PFNGLRASTERPOS3IPROC) ( GLint x, GLint y, GLint z ); +typedef void (APIENTRYP PFNGLRASTERPOS3SPROC) ( GLshort x, GLshort y, GLshort z ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DPROC) ( GLdouble x, GLdouble y, GLdouble z, GLdouble w ); +typedef void (APIENTRYP PFNGLRASTERPOS4FPROC) ( GLfloat x, GLfloat y, GLfloat z, GLfloat w ); +typedef void (APIENTRYP PFNGLRASTERPOS4IPROC) ( GLint x, GLint y, GLint z, GLint w ); +typedef void (APIENTRYP PFNGLRASTERPOS4SPROC) ( GLshort x, GLshort y, GLshort z, GLshort w ); + +typedef void (APIENTRYP PFNGLRASTERPOS2DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS2SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS3DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS3SVPROC) ( const GLshort *v ); + +typedef void (APIENTRYP PFNGLRASTERPOS4DVPROC) ( const GLdouble *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4FVPROC) ( const GLfloat *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4IVPROC) ( const GLint *v ); +typedef void (APIENTRYP PFNGLRASTERPOS4SVPROC) ( const GLshort *v ); + + +typedef void (APIENTRYP PFNGLRECTDPROC) ( GLdouble x1, GLdouble y1, GLdouble x2, GLdouble y2 ); +typedef void (APIENTRYP PFNGLRECTFPROC) ( GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2 ); +typedef void (APIENTRYP PFNGLRECTIPROC) ( GLint x1, GLint y1, GLint x2, GLint y2 ); +typedef void (APIENTRYP PFNGLRECTSPROC) ( GLshort x1, GLshort y1, GLshort x2, GLshort y2 ); + + +typedef void (APIENTRYP PFNGLRECTDVPROC) ( const GLdouble *v1, const GLdouble *v2 ); +typedef void (APIENTRYP PFNGLRECTFVPROC) ( const GLfloat *v1, const GLfloat *v2 ); +typedef void (APIENTRYP PFNGLRECTIVPROC) ( const GLint *v1, const GLint *v2 ); +typedef void (APIENTRYP PFNGLRECTSVPROC) ( const GLshort *v1, const GLshort *v2 ); + + +/* + * Vertex Arrays (1.1) + */ + +typedef void (APIENTRYP PFNGLVERTEXPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLNORMALPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLCOLORPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLINDEXPOINTERPROC) ( GLenum type, GLsizei stride, + const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLTEXCOORDPOINTERPROC) ( GLint size, GLenum type, + GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLEDGEFLAGPOINTERPROC) ( GLsizei stride, const GLvoid *ptr ); + +typedef void (APIENTRYP PFNGLGETPOINTERVPROC) ( GLenum pname, GLvoid **params ); + +typedef void (APIENTRYP PFNGLARRAYELEMENTPROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLDRAWARRAYSPROC) ( GLenum mode, GLint first, GLsizei count ); + +typedef void (APIENTRYP PFNGLDRAWELEMENTSPROC) ( GLenum mode, GLsizei count, + GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLINTERLEAVEDARRAYSPROC) ( GLenum format, GLsizei stride, + const GLvoid *pointer ); + +/* + * Lighting + */ + +typedef void (APIENTRYP PFNGLSHADEMODELPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLLIGHTFPROC) ( GLenum light, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTIPROC) ( GLenum light, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTFVPROC) ( GLenum light, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTIVPROC) ( GLenum light, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETLIGHTFVPROC) ( GLenum light, GLenum pname, + GLfloat *params ); +typedef void (APIENTRYP PFNGLGETLIGHTIVPROC) ( GLenum light, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLLIGHTMODELFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLLIGHTMODELIPROC) ( GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLLIGHTMODELFVPROC) ( GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLLIGHTMODELIVPROC) ( GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLMATERIALFPROC) ( GLenum face, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLMATERIALIPROC) ( GLenum face, GLenum pname, GLint param ); +typedef void (APIENTRYP PFNGLMATERIALFVPROC) ( GLenum face, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLMATERIALIVPROC) ( GLenum face, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETMATERIALFVPROC) ( GLenum face, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETMATERIALIVPROC) ( GLenum face, GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLCOLORMATERIALPROC) ( GLenum face, GLenum mode ); + + +/* + * Raster functions + */ + +typedef void (APIENTRYP PFNGLPIXELZOOMPROC) ( GLfloat xfactor, GLfloat yfactor ); + +typedef void (APIENTRYP PFNGLPIXELSTOREFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELSTOREIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELTRANSFERFPROC) ( GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLPIXELTRANSFERIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLPIXELMAPFVPROC) ( GLenum map, GLsizei mapsize, + const GLfloat *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUIVPROC) ( GLenum map, GLsizei mapsize, + const GLuint *values ); +typedef void (APIENTRYP PFNGLPIXELMAPUSVPROC) ( GLenum map, GLsizei mapsize, + const GLushort *values ); + +typedef void (APIENTRYP PFNGLGETPIXELMAPFVPROC) ( GLenum map, GLfloat *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUIVPROC) ( GLenum map, GLuint *values ); +typedef void (APIENTRYP PFNGLGETPIXELMAPUSVPROC) ( GLenum map, GLushort *values ); + +typedef void (APIENTRYP PFNGLBITMAPPROC) ( GLsizei width, GLsizei height, + GLfloat xorig, GLfloat yorig, + GLfloat xmove, GLfloat ymove, + const GLubyte *bitmap ); + +typedef void (APIENTRYP PFNGLREADPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLDRAWPIXELSPROC) ( GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLCOPYPIXELSPROC) ( GLint x, GLint y, + GLsizei width, GLsizei height, + GLenum type ); + +/* + * Stenciling + */ + +typedef void (APIENTRYP PFNGLSTENCILFUNCPROC) ( GLenum func, GLint ref, GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILMASKPROC) ( GLuint mask ); + +typedef void (APIENTRYP PFNGLSTENCILOPPROC) ( GLenum fail, GLenum zfail, GLenum zpass ); + +typedef void (APIENTRYP PFNGLCLEARSTENCILPROC) ( GLint s ); + + + +/* + * Texture mapping + */ + +typedef void (APIENTRYP PFNGLTEXGENDPROC) ( GLenum coord, GLenum pname, GLdouble param ); +typedef void (APIENTRYP PFNGLTEXGENFPROC) ( GLenum coord, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXGENIPROC) ( GLenum coord, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXGENDVPROC) ( GLenum coord, GLenum pname, const GLdouble *params ); +typedef void (APIENTRYP PFNGLTEXGENFVPROC) ( GLenum coord, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXGENIVPROC) ( GLenum coord, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXGENDVPROC) ( GLenum coord, GLenum pname, GLdouble *params ); +typedef void (APIENTRYP PFNGLGETTEXGENFVPROC) ( GLenum coord, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXGENIVPROC) ( GLenum coord, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXENVFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXENVIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXENVFVPROC) ( GLenum target, GLenum pname, const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXENVIVPROC) ( GLenum target, GLenum pname, const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXENVFVPROC) ( GLenum target, GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXENVIVPROC) ( GLenum target, GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXPARAMETERFPROC) ( GLenum target, GLenum pname, GLfloat param ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIPROC) ( GLenum target, GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLTEXPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); +typedef void (APIENTRYP PFNGLTEXPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXPARAMETERFVPROC) ( GLenum target, + GLenum pname, GLfloat *params); +typedef void (APIENTRYP PFNGLGETTEXPARAMETERIVPROC) ( GLenum target, + GLenum pname, GLint *params ); + +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERFVPROC) ( GLenum target, GLint level, + GLenum pname, GLfloat *params ); +typedef void (APIENTRYP PFNGLGETTEXLEVELPARAMETERIVPROC) ( GLenum target, GLint level, + GLenum pname, GLint *params ); + + +typedef void (APIENTRYP PFNGLTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLint border, GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLGETTEXIMAGEPROC) ( GLenum target, GLint level, + GLenum format, GLenum type, + GLvoid *pixels ); + + +/* 1.1 functions */ + +typedef void (APIENTRYP PFNGLGENTEXTURESPROC) ( GLsizei n, GLuint *textures ); + +typedef void (APIENTRYP PFNGLDELETETEXTURESPROC) ( GLsizei n, const GLuint *textures); + +typedef void (APIENTRYP PFNGLBINDTEXTUREPROC) ( GLenum target, GLuint texture ); + +typedef void (APIENTRYP PFNGLPRIORITIZETEXTURESPROC) ( GLsizei n, + const GLuint *textures, + const GLclampf *priorities ); + +typedef GLboolean (APIENTRYP PFNGLARETEXTURESRESIDENTPROC) ( GLsizei n, + const GLuint *textures, + GLboolean *residences ); + +typedef GLboolean (APIENTRYP PFNGLISTEXTUREPROC) ( GLuint texture ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, + GLsizei width, GLenum format, + GLenum type, const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLsizei width, GLsizei height, + GLenum format, GLenum type, + const GLvoid *pixels ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE1DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXIMAGE2DPROC) ( GLenum target, GLint level, + GLenum internalformat, + GLint x, GLint y, + GLsizei width, GLsizei height, + GLint border ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint x, GLint y, + GLsizei width ); + + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint x, GLint y, + GLsizei width, GLsizei height ); + + +/* + * Evaluators + */ + +typedef void (APIENTRYP PFNGLMAP1DPROC) ( GLenum target, GLdouble u1, GLdouble u2, + GLint stride, + GLint order, const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP1FPROC) ( GLenum target, GLfloat u1, GLfloat u2, + GLint stride, + GLint order, const GLfloat *points ); + +typedef void (APIENTRYP PFNGLMAP2DPROC) ( GLenum target, + GLdouble u1, GLdouble u2, GLint ustride, GLint uorder, + GLdouble v1, GLdouble v2, GLint vstride, GLint vorder, + const GLdouble *points ); +typedef void (APIENTRYP PFNGLMAP2FPROC) ( GLenum target, + GLfloat u1, GLfloat u2, GLint ustride, GLint uorder, + GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, + const GLfloat *points ); + +typedef void (APIENTRYP PFNGLGETMAPDVPROC) ( GLenum target, GLenum query, GLdouble *v ); +typedef void (APIENTRYP PFNGLGETMAPFVPROC) ( GLenum target, GLenum query, GLfloat *v ); +typedef void (APIENTRYP PFNGLGETMAPIVPROC) ( GLenum target, GLenum query, GLint *v ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DPROC) ( GLdouble u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FPROC) ( GLfloat u ); + +typedef void (APIENTRYP PFNGLEVALCOORD1DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD1FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DPROC) ( GLdouble u, GLdouble v ); +typedef void (APIENTRYP PFNGLEVALCOORD2FPROC) ( GLfloat u, GLfloat v ); + +typedef void (APIENTRYP PFNGLEVALCOORD2DVPROC) ( const GLdouble *u ); +typedef void (APIENTRYP PFNGLEVALCOORD2FVPROC) ( const GLfloat *u ); + +typedef void (APIENTRYP PFNGLMAPGRID1DPROC) ( GLint un, GLdouble u1, GLdouble u2 ); +typedef void (APIENTRYP PFNGLMAPGRID1FPROC) ( GLint un, GLfloat u1, GLfloat u2 ); + +typedef void (APIENTRYP PFNGLMAPGRID2DPROC) ( GLint un, GLdouble u1, GLdouble u2, + GLint vn, GLdouble v1, GLdouble v2 ); +typedef void (APIENTRYP PFNGLMAPGRID2FPROC) ( GLint un, GLfloat u1, GLfloat u2, + GLint vn, GLfloat v1, GLfloat v2 ); + +typedef void (APIENTRYP PFNGLEVALPOINT1PROC) ( GLint i ); + +typedef void (APIENTRYP PFNGLEVALPOINT2PROC) ( GLint i, GLint j ); + +typedef void (APIENTRYP PFNGLEVALMESH1PROC) ( GLenum mode, GLint i1, GLint i2 ); + +typedef void (APIENTRYP PFNGLEVALMESH2PROC) ( GLenum mode, GLint i1, GLint i2, GLint j1, GLint j2 ); + + +/* + * Fog + */ + +typedef void (APIENTRYP PFNGLFOGFPROC) ( GLenum pname, GLfloat param ); + +typedef void (APIENTRYP PFNGLFOGIPROC) ( GLenum pname, GLint param ); + +typedef void (APIENTRYP PFNGLFOGFVPROC) ( GLenum pname, const GLfloat *params ); + +typedef void (APIENTRYP PFNGLFOGIVPROC) ( GLenum pname, const GLint *params ); + + +/* + * Selection and Feedback + */ + +typedef void (APIENTRYP PFNGLFEEDBACKBUFFERPROC) ( GLsizei size, GLenum type, GLfloat *buffer ); + +typedef void (APIENTRYP PFNGLPASSTHROUGHPROC) ( GLfloat token ); + +typedef void (APIENTRYP PFNGLSELECTBUFFERPROC) ( GLsizei size, GLuint *buffer ); + +typedef void (APIENTRYP PFNGLINITNAMESPROC) ( void ); + +typedef void (APIENTRYP PFNGLLOADNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPUSHNAMEPROC) ( GLuint name ); + +typedef void (APIENTRYP PFNGLPOPNAMEPROC) ( void ); +#endif /* @@ -1528,6 +2229,8 @@ GLAPI void GLAPIENTRY glPopName( void ); #define GL_MAX_3D_TEXTURE_SIZE 0x8073 #define GL_TEXTURE_BINDING_3D 0x806A +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glDrawRangeElements( GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); @@ -1551,6 +2254,34 @@ GLAPI void GLAPIENTRY glCopyTexSubImage3D( GLenum target, GLint level, GLint y, GLsizei width, GLsizei height ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) ( GLenum mode, GLuint start, + GLuint end, GLsizei count, GLenum type, const GLvoid *indices ); + +typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) ( GLenum target, GLint level, + GLint internalFormat, + GLsizei width, GLsizei height, + GLsizei depth, GLint border, + GLenum format, GLenum type, + const GLvoid *pixels ); + +typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLsizei width, + GLsizei height, GLsizei depth, + GLenum format, + GLenum type, const GLvoid *pixels); + +typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, + GLint xoffset, GLint yoffset, + GLint zoffset, GLint x, + GLint y, GLsizei width, + GLsizei height ); + +#endif + typedef void (APIENTRYP PFNGLDRAWRANGEELEMENTSPROC) (GLenum mode, GLuint start, GLuint end, GLsizei count, GLenum type, const GLvoid *indices); typedef void (APIENTRYP PFNGLTEXIMAGE3DPROC) (GLenum target, GLint level, GLint internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLenum format, GLenum type, const GLvoid *pixels); typedef void (APIENTRYP PFNGLTEXSUBIMAGE3DPROC) (GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLenum type, const GLvoid *pixels); @@ -1638,6 +2369,8 @@ typedef void (APIENTRYP PFNGLCOPYTEXSUBIMAGE3DPROC) (GLenum target, GLint level, #define GL_BLEND_COLOR 0x8005 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glColorTable( GLenum target, GLenum internalformat, GLsizei width, GLenum format, GLenum type, const GLvoid *table ); @@ -1746,6 +2479,119 @@ GLAPI void GLAPIENTRY glSeparableFilter2D( GLenum target, GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLsizei width, GLenum format, + GLenum type, const GLvoid *table ); + +typedef void (APIENTRYP PFNGLCOLORSUBTABLEPROC) ( GLenum target, + GLsizei start, GLsizei count, + GLenum format, GLenum type, + const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERIVPROC) (GLenum target, GLenum pname, + const GLint *params); + +typedef void (APIENTRYP PFNGLCOLORTABLEPARAMETERFVPROC) (GLenum target, GLenum pname, + const GLfloat *params); + +typedef void (APIENTRYP PFNGLCOPYCOLORSUBTABLEPROC) ( GLenum target, GLsizei start, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCOLORTABLEPROC) ( GLenum target, GLenum internalformat, + GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *table ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCOLORTABLEPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLBLENDEQUATIONPROC) ( GLenum mode ); + +typedef void (APIENTRYP PFNGLBLENDCOLORPROC) ( GLclampf red, GLclampf green, + GLclampf blue, GLclampf alpha ); + +typedef void (APIENTRYP PFNGLHISTOGRAMPROC) ( GLenum target, GLsizei width, + GLenum internalformat, GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETHISTOGRAMPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum type, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETHISTOGRAMPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLMINMAXPROC) ( GLenum target, GLenum internalformat, + GLboolean sink ); + +typedef void (APIENTRYP PFNGLRESETMINMAXPROC) ( GLenum target ); + +typedef void (APIENTRYP PFNGLGETMINMAXPROC) ( GLenum target, GLboolean reset, + GLenum format, GLenum types, + GLvoid *values ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETMINMAXPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLenum format, GLenum type, + const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *image ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFPROC) ( GLenum target, GLenum pname, + GLfloat params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + const GLfloat *params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIPROC) ( GLenum target, GLenum pname, + GLint params ); + +typedef void (APIENTRYP PFNGLCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + const GLint *params ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER1DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width ); + +typedef void (APIENTRYP PFNGLCOPYCONVOLUTIONFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLint x, GLint y, GLsizei width, + GLsizei height); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *image ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERFVPROC) ( GLenum target, GLenum pname, + GLfloat *params ); + +typedef void (APIENTRYP PFNGLGETCONVOLUTIONPARAMETERIVPROC) ( GLenum target, GLenum pname, + GLint *params ); + +typedef void (APIENTRYP PFNGLSEPARABLEFILTER2DPROC) ( GLenum target, + GLenum internalformat, GLsizei width, GLsizei height, GLenum format, + GLenum type, const GLvoid *row, const GLvoid *column ); + +typedef void (APIENTRYP PFNGLGETSEPARABLEFILTERPROC) ( GLenum target, GLenum format, + GLenum type, GLvoid *row, GLvoid *column, GLvoid *span ); + +#endif + @@ -1858,6 +2704,8 @@ GLAPI void GLAPIENTRY glGetSeparableFilter( GLenum target, GLenum format, /* texture_border_clamp */ #define GL_CLAMP_TO_BORDER 0x812D +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTexture( GLenum texture ); GLAPI void GLAPIENTRY glClientActiveTexture( GLenum texture ); @@ -1951,6 +2799,104 @@ GLAPI void GLAPIENTRY glMultTransposeMatrixf( const GLfloat m[16] ); GLAPI void GLAPIENTRY glSampleCoverage( GLclampf value, GLboolean invert ); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREPROC) ( GLenum texture ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE1DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE2DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXIMAGE3DPROC) ( GLenum target, GLint level, GLenum internalformat, GLsizei width, GLsizei height, GLsizei depth, GLint border, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE1DPROC) ( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE2DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLCOMPRESSEDTEXSUBIMAGE3DPROC) ( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint zoffset, GLsizei width, GLsizei height, GLsizei depth, GLenum format, GLsizei imageSize, const GLvoid *data ); + +typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) ( GLenum target, GLint lod, GLvoid *img ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DPROC) ( GLenum target, GLdouble s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FPROC) ( GLenum target, GLfloat s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IPROC) ( GLenum target, GLint s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SPROC) ( GLenum target, GLshort s ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DPROC) ( GLenum target, GLdouble s, GLdouble t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FPROC) ( GLenum target, GLfloat s, GLfloat t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IPROC) ( GLenum target, GLint s, GLint t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SPROC) ( GLenum target, GLshort s, GLshort t ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IPROC) ( GLenum target, GLint s, GLint t, GLint r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVPROC) ( GLenum target, const GLshort *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DPROC) ( GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVPROC) ( GLenum target, const GLdouble *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FPROC) ( GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVPROC) ( GLenum target, const GLfloat *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IPROC) ( GLenum target, GLint s, GLint t, GLint r, GLint q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVPROC) ( GLenum target, const GLint *v ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SPROC) ( GLenum target, GLshort s, GLshort t, GLshort r, GLshort q ); + +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVPROC) ( GLenum target, const GLshort *v ); + + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLLOADTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXDPROC) ( const GLdouble m[16] ); + +typedef void (APIENTRYP PFNGLMULTTRANSPOSEMATRIXFPROC) ( const GLfloat m[16] ); + +typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) ( GLclampf value, GLboolean invert ); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREPROC) (GLenum texture); typedef void (APIENTRYP PFNGLSAMPLECOVERAGEPROC) (GLclampf value, GLboolean invert); @@ -2006,6 +2952,8 @@ typedef void (APIENTRYP PFNGLGETCOMPRESSEDTEXIMAGEPROC) (GLenum target, GLint le #define GL_CLIENT_ACTIVE_TEXTURE_ARB 0x84E1 #define GL_MAX_TEXTURE_UNITS_ARB 0x84E2 +#ifndef SDL_OPENGL_1_NO_PROTOTYPES + GLAPI void GLAPIENTRY glActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glClientActiveTextureARB(GLenum texture); GLAPI void GLAPIENTRY glMultiTexCoord1dARB(GLenum target, GLdouble s); @@ -2041,6 +2989,46 @@ GLAPI void GLAPIENTRY glMultiTexCoord4ivARB(GLenum target, const GLint *v); GLAPI void GLAPIENTRY glMultiTexCoord4sARB(GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); GLAPI void GLAPIENTRY glMultiTexCoord4svARB(GLenum target, const GLshort *v); +#endif +#ifdef SDL_OPENGL_1_FUNCTION_TYPEDEFS + +typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FARBPROC) (GLenum target, GLfloat s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IARBPROC) (GLenum target, GLint s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SARBPROC) (GLenum target, GLshort s); +typedef void (APIENTRYP PFNGLMULTITEXCOORD1SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DARBPROC) (GLenum target, GLdouble s, GLdouble t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FARBPROC) (GLenum target, GLfloat s, GLfloat t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IARBPROC) (GLenum target, GLint s, GLint t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SARBPROC) (GLenum target, GLshort s, GLshort t); +typedef void (APIENTRYP PFNGLMULTITEXCOORD2SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IARBPROC) (GLenum target, GLint s, GLint t, GLint r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r); +typedef void (APIENTRYP PFNGLMULTITEXCOORD3SVARBPROC) (GLenum target, const GLshort *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DARBPROC) (GLenum target, GLdouble s, GLdouble t, GLdouble r, GLdouble q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4DVARBPROC) (GLenum target, const GLdouble *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FARBPROC) (GLenum target, GLfloat s, GLfloat t, GLfloat r, GLfloat q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4FVARBPROC) (GLenum target, const GLfloat *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IARBPROC) (GLenum target, GLint s, GLint t, GLint r, GLint q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4IVARBPROC) (GLenum target, const GLint *v); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SARBPROC) (GLenum target, GLshort s, GLshort t, GLshort r, GLshort q); +typedef void (APIENTRYP PFNGLMULTITEXCOORD4SVARBPROC) (GLenum target, const GLshort *v); + +#endif + typedef void (APIENTRYP PFNGLACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLCLIENTACTIVETEXTUREARBPROC) (GLenum texture); typedef void (APIENTRYP PFNGLMULTITEXCOORD1DARBPROC) (GLenum target, GLdouble s); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h index bde4d74..4fb9a4b 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h index ba19601..365898a 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_opengles2.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h index cda4f0f..5182eeb 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pen.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -39,7 +39,9 @@ #ifndef SDL_pen_h_ #define SDL_pen_h_ -#include +#include +#include +#include /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus @@ -55,24 +57,39 @@ extern "C" { * consistent as long as SDL can recognize a tool to be the same pen; but if a * pen physically leaves the area and returns, it might get a new ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenID; +/** + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_MOUSEID ((SDL_MouseID)-2) + +/** + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PEN_TOUCHID ((SDL_TouchID)-2) + /** * Pen input flags, as reported by various pen events' `pen_state` field. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PenInputFlags; -#define SDL_PEN_INPUT_DOWN (1u << 0) /**< & to see if pen is pressed down */ -#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< & to see if button 1 is pressed */ -#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< & to see if button 2 is pressed */ -#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< & to see if button 3 is pressed */ -#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< & to see if button 4 is pressed */ -#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< & to see if button 5 is pressed */ -#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< & to see if eraser tip is used */ + +#define SDL_PEN_INPUT_DOWN (1u << 0) /**< pen is pressed down */ +#define SDL_PEN_INPUT_BUTTON_1 (1u << 1) /**< button 1 is pressed */ +#define SDL_PEN_INPUT_BUTTON_2 (1u << 2) /**< button 2 is pressed */ +#define SDL_PEN_INPUT_BUTTON_3 (1u << 3) /**< button 3 is pressed */ +#define SDL_PEN_INPUT_BUTTON_4 (1u << 4) /**< button 4 is pressed */ +#define SDL_PEN_INPUT_BUTTON_5 (1u << 5) /**< button 5 is pressed */ +#define SDL_PEN_INPUT_ERASER_TIP (1u << 30) /**< eraser tip is used */ /** * Pen axis indices. @@ -87,20 +104,18 @@ typedef Uint32 SDL_PenInputFlags; * * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PenAxis { SDL_PEN_AXIS_PRESSURE, /**< Pen pressure. Unidirectional: 0 to 1.0 */ - SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). - The physical max/min tilt may be smaller than -90.0 / 90.0, check SDL_PenCapabilityInfo */ - SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). - The physical max/min tilt may be smaller than -90.0 / 90.0 check SDL_PenCapabilityInfo */ + SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0 to 90.0 (left-to-right). */ + SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0 to 90.0 (top-to-down). */ SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0 to 1.0 */ SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180 to 179.9 (clockwise, 0 is facing up, -180.0 is facing down). */ SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0 to 1.0 */ SDL_PEN_AXIS_TANGENTIAL_PRESSURE, /**< Pressure from squeezing the pen ("barrel pressure"). */ - SDL_PEN_NUM_AXES /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ + SDL_PEN_AXIS_COUNT /**< Total known pen axis types in this version of SDL. This number may grow in future releases! */ } SDL_PenAxis; /* Ends C function definitions when using C++ */ @@ -110,4 +125,3 @@ typedef enum SDL_PenAxis #endif /* SDL_pen_h_ */ -/* vi: set ts=4 sw=4 expandtab: */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h index 3825dd5..b6f38ac 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_pixels.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,59 @@ /** * # CategoryPixels * - * Pixel management. + * SDL offers facilities for pixel management. + * + * Largely these facilities deal with pixel _format_: what does this set of + * bits represent? + * + * If you mostly want to think of a pixel as some combination of red, green, + * blue, and maybe alpha intensities, this is all pretty straightforward, and + * in many cases, is enough information to build a perfectly fine game. + * + * However, the actual definition of a pixel is more complex than that: + * + * Pixels are a representation of a color in a particular color space. + * + * The first characteristic of a color space is the color type. SDL + * understands two different color types, RGB and YCbCr, or in SDL also + * referred to as YUV. + * + * RGB colors consist of red, green, and blue channels of color that are added + * together to represent the colors we see on the screen. + * + * https://en.wikipedia.org/wiki/RGB_color_model + * + * YCbCr colors represent colors as a Y luma brightness component and red and + * blue chroma color offsets. This color representation takes advantage of the + * fact that the human eye is more sensitive to brightness than the color in + * an image. The Cb and Cr components are often compressed and have lower + * resolution than the luma component. + * + * https://en.wikipedia.org/wiki/YCbCr + * + * When the color information in YCbCr is compressed, the Y pixels are left at + * full resolution and each Cr and Cb pixel represents an average of the color + * information in a block of Y pixels. The chroma location determines where in + * that block of pixels the color information is coming from. + * + * The color range defines how much of the pixel to use when converting a + * pixel into a color on the display. When the full color range is used, the + * entire numeric range of the pixel bits is significant. When narrow color + * range is used, for historical reasons, the pixel uses only a portion of the + * numeric range to represent colors. + * + * The color primaries and white point are a definition of the colors in the + * color space relative to the standard XYZ color space. + * + * https://en.wikipedia.org/wiki/CIE_1931_color_space + * + * The transfer characteristic, or opto-electrical transfer function (OETF), + * is the way a color is converted from mathematically linear space into a + * non-linear output signals. + * + * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics + * + * The matrix coefficients are used to convert between YCbCr and RGB colors. */ #ifndef SDL_pixels_h_ @@ -41,22 +93,44 @@ extern "C" { /** * A fully opaque 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_TRANSPARENT */ #define SDL_ALPHA_OPAQUE 255 +/** + * A fully opaque floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_TRANSPARENT_FLOAT + */ +#define SDL_ALPHA_OPAQUE_FLOAT 1.0f + /** * A fully transparent 8-bit alpha value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_ALPHA_OPAQUE */ #define SDL_ALPHA_TRANSPARENT 0 -/** Pixel type. */ +/** + * A fully transparent floating point alpha value. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_ALPHA_OPAQUE_FLOAT + */ +#define SDL_ALPHA_TRANSPARENT_FLOAT 0.0f + +/** + * Pixel type. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, @@ -75,7 +149,11 @@ typedef enum SDL_PixelType SDL_PIXELTYPE_INDEX2 } SDL_PixelType; -/** Bitmap pixel order, high bit -> low bit. */ +/** + * Bitmap pixel order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, @@ -83,7 +161,11 @@ typedef enum SDL_BitmapOrder SDL_BITMAPORDER_1234 } SDL_BitmapOrder; -/** Packed component order, high bit -> low bit. */ +/** + * Packed component order, high bit -> low bit. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, @@ -97,7 +179,11 @@ typedef enum SDL_PackedOrder SDL_PACKEDORDER_BGRA } SDL_PackedOrder; -/** Array component order, low byte -> high byte. */ +/** + * Array component order, low byte -> high byte. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, @@ -109,7 +195,11 @@ typedef enum SDL_ArrayOrder SDL_ARRAYORDER_ABGR } SDL_ArrayOrder; -/** Packed component layout. */ +/** + * Packed component layout. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, @@ -123,25 +213,172 @@ typedef enum SDL_PackedLayout SDL_PACKEDLAYOUT_1010102 } SDL_PackedLayout; +/** + * A macro for defining custom FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_YV12 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') + * ``` + * + * \param A the first character of the FourCC code. + * \param B the second character of the FourCC code. + * \param C the third character of the FourCC code. + * \param D the fourth character of the FourCC code. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) +/** + * A macro for defining custom non-FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) + * ``` + * + * \param type the type of the new format, probably a SDL_PixelType value. + * \param order the order of the new format, probably a SDL_BitmapOrder, + * SDL_PackedOrder, or SDL_ArrayOrder value. + * \param layout the layout of the new format, probably an SDL_PackedLayout + * value or zero. + * \param bits the number of bits per pixel of the new format. + * \param bytes the number of bytes per pixel of the new format. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ ((bits) << 8) | ((bytes) << 0)) -#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) -#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) -#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) -#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) -#define SDL_BITSPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU) || \ - ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF)) +/** + * A macro to retrieve the flags of an SDL_PixelFormat. + * + * This macro is generally not needed directly by an app, which should use + * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. + * + * \param format an SDL_PixelFormat to check. + * \returns the flags of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) +/** + * A macro to retrieve the type of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PixelType enumeration. + * + * \param format an SDL_PixelFormat to check. + * \returns the type of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) + +/** + * A macro to retrieve the order of an SDL_PixelFormat. + * + * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or + * SDL_ArrayOrder enumerations, depending on the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the order of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) + +/** + * A macro to retrieve the layout of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PackedLayout enumeration, or zero if a + * layout doesn't make sense for the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the layout of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) + +/** + * A macro to determine an SDL_PixelFormat's bits per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats will report zero here, as it rarely makes sense to measure + * them per-pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bits-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BYTESPERPIXEL + */ +#define SDL_BITSPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) + +/** + * A macro to determine an SDL_PixelFormat's bytes per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats do their best here, but many of them don't have a meaningful + * measurement of bytes per pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bytes-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_BITSPERPIXEL + */ +#define SDL_BYTESPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? \ + ((((format) == SDL_PIXELFORMAT_YUY2) || \ + ((format) == SDL_PIXELFORMAT_UYVY) || \ + ((format) == SDL_PIXELFORMAT_YVYU) || \ + ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) + + +/** + * A macro to determine if an SDL_PixelFormat is an indexed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is indexed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -149,12 +386,38 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) +/** + * A macro to determine if an SDL_PixelFormat is a packed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is packed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_PACKED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) +/** + * A macro to determine if an SDL_PixelFormat is an array format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is an array, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -163,25 +426,84 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -#define SDL_ISPIXELFORMAT_ALPHA(format) \ - ((SDL_ISPIXELFORMAT_PACKED(format) && \ - ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ - (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA)))) - +/** + * A macro to determine if an SDL_PixelFormat is a 10-bit format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_10BIT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) +/** + * A macro to determine if an SDL_PixelFormat is a floating point format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) -/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ -#define SDL_ISPIXELFORMAT_FOURCC(format) \ +/** + * A macro to determine if an SDL_PixelFormat has an alpha channel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_ALPHA(format) \ + ((SDL_ISPIXELFORMAT_PACKED(format) && \ + ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))) || \ + (SDL_ISPIXELFORMAT_ARRAY(format) && \ + ((SDL_PIXELORDER(format) == SDL_ARRAYORDER_ARGB) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_RGBA) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ + (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) + + +/** + * A macro to determine if an SDL_PixelFormat is a "FourCC" format. + * + * This covers custom and other unusual formats. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this enum, update SDL_GetPixelFormatName() */ @@ -221,7 +543,7 @@ typedef enum SDL_PackedLayout * an alias for ABGR8888 on little-endian CPUs like x86, or an alias for * RGBA8888 on big-endian CPUs. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PixelFormat { @@ -351,59 +673,35 @@ typedef enum SDL_PixelFormat /* SDL_DEFINE_PIXELFOURCC('N', 'V', '2', '1'), */ SDL_PIXELFORMAT_P010 = 0x30313050u, /**< Planar mode: Y + U/V interleaved (2 planes) */ /* SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'), */ - SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu /**< Android video texture format */ + SDL_PIXELFORMAT_EXTERNAL_OES = 0x2053454fu, /**< Android video texture format */ /* SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ') */ + + /* Aliases for RGBA byte arrays of color data, for the current platform */ + #if SDL_BYTEORDER == SDL_BIG_ENDIAN + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_RGBX8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_XBGR8888 + #else + SDL_PIXELFORMAT_RGBA32 = SDL_PIXELFORMAT_ABGR8888, + SDL_PIXELFORMAT_ARGB32 = SDL_PIXELFORMAT_BGRA8888, + SDL_PIXELFORMAT_BGRA32 = SDL_PIXELFORMAT_ARGB8888, + SDL_PIXELFORMAT_ABGR32 = SDL_PIXELFORMAT_RGBA8888, + SDL_PIXELFORMAT_RGBX32 = SDL_PIXELFORMAT_XBGR8888, + SDL_PIXELFORMAT_XRGB32 = SDL_PIXELFORMAT_BGRX8888, + SDL_PIXELFORMAT_BGRX32 = SDL_PIXELFORMAT_XRGB8888, + SDL_PIXELFORMAT_XBGR32 = SDL_PIXELFORMAT_RGBX8888 + #endif } SDL_PixelFormat; -/* Aliases for RGBA byte arrays of color data, for the current platform */ -#if SDL_BYTEORDER == SDL_BIG_ENDIAN -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_RGBX8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_XBGR8888 -#else -#define SDL_PIXELFORMAT_RGBA32 SDL_PIXELFORMAT_ABGR8888 -#define SDL_PIXELFORMAT_ARGB32 SDL_PIXELFORMAT_BGRA8888 -#define SDL_PIXELFORMAT_BGRA32 SDL_PIXELFORMAT_ARGB8888 -#define SDL_PIXELFORMAT_ABGR32 SDL_PIXELFORMAT_RGBA8888 -#define SDL_PIXELFORMAT_RGBX32 SDL_PIXELFORMAT_XBGR8888 -#define SDL_PIXELFORMAT_XRGB32 SDL_PIXELFORMAT_BGRX8888 -#define SDL_PIXELFORMAT_BGRX32 SDL_PIXELFORMAT_XRGB8888 -#define SDL_PIXELFORMAT_XBGR32 SDL_PIXELFORMAT_RGBX8888 -#endif - -/** - * Pixels are a representation of a color in a particular color space. - * - * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV. - * - * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen. - * https://en.wikipedia.org/wiki/RGB_color_model - * - * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component. - * https://en.wikipedia.org/wiki/YCbCr - * - * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from. - * - * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors. - * - * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space. - * https://en.wikipedia.org/wiki/CIE_1931_color_space - * - * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals. - * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics - * - * The matrix coefficients are used to convert between YCbCr and RGB colors. - */ - /** * Colorspace color type. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorType { @@ -416,7 +714,7 @@ typedef enum SDL_ColorType * Colorspace color range, as described by * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorRange { @@ -429,7 +727,7 @@ typedef enum SDL_ColorRange * Colorspace color primaries, as described by * https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ColorPrimaries { @@ -454,7 +752,7 @@ typedef enum SDL_ColorPrimaries * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TransferCharacteristics { @@ -484,7 +782,7 @@ typedef enum SDL_TransferCharacteristics * * These are as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_MatrixCoefficients { @@ -508,7 +806,7 @@ typedef enum SDL_MatrixCoefficients /** * Colorspace chroma sample location. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ChromaLocation { @@ -520,22 +818,177 @@ typedef enum SDL_ChromaLocation /* Colorspace definition */ + +/** + * A macro for defining custom SDL_Colorspace formats. + * + * For example, defining SDL_COLORSPACE_SRGB looks like this: + * + * ```c + * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + * SDL_COLOR_RANGE_FULL, + * SDL_COLOR_PRIMARIES_BT709, + * SDL_TRANSFER_CHARACTERISTICS_SRGB, + * SDL_MATRIX_COEFFICIENTS_IDENTITY, + * SDL_CHROMA_LOCATION_NONE) + * ``` + * + * \param type the type of the new format, probably an SDL_ColorType value. + * \param range the range of the new format, probably a SDL_ColorRange value. + * \param primaries the primaries of the new format, probably an + * SDL_ColorPrimaries value. + * \param transfer the transfer characteristics of the new format, probably an + * SDL_TransferCharacteristics value. + * \param matrix the matrix coefficients of the new format, probably an + * SDL_MatrixCoefficients value. + * \param chroma the chroma sample location of the new format, probably an + * SDL_ChromaLocation value. + * \returns a format value in the style of SDL_Colorspace. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) -#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F) -#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F) -#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F) -#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) -#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) -#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F) +/** + * A macro to retrieve the type of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorType for `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) -#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) -#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) -#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) -#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) -#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) +/** + * A macro to retrieve the range of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorRange of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) + +/** + * A macro to retrieve the chroma sample location of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ChromaLocation of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) + +/** + * A macro to retrieve the primaries of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorPrimaries of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) + +/** + * A macro to retrieve the transfer characteristics of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_TransferCharacteristics of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) + +/** + * A macro to retrieve the matrix coefficients of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_MatrixCoefficients of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) + +/** + * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix + * coefficients. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT601 or BT470BG, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) + +/** + * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) + +/** + * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix + * coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT2020_NCL, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) + +/** + * A macro to determine if an SDL_Colorspace has a limited range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if limited range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) + +/** + * A macro to determine if an SDL_Colorspace has a full range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if full range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. @@ -544,7 +997,7 @@ typedef enum SDL_ChromaLocation * function, etc.), this is not an exhaustive list, but rather a * representative sample of the kinds of colorspaces supported in SDL. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_ColorPrimaries * \sa SDL_ColorRange @@ -631,7 +1084,7 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ - SDL_COLORSPACE_BT2020_FULL = 0x22102609u /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ + SDL_COLORSPACE_BT2020_FULL = 0x22102609u, /**< Equivalent to DXGI_COLOR_SPACE_YCBCR_FULL_G22_LEFT_P2020 */ /* SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_YCBCR, SDL_COLOR_RANGE_FULL, SDL_COLOR_PRIMARIES_BT2020, @@ -639,15 +1092,10 @@ typedef enum SDL_Colorspace SDL_MATRIX_COEFFICIENTS_BT2020_NCL, SDL_CHROMA_LOCATION_LEFT), */ + SDL_COLORSPACE_RGB_DEFAULT = SDL_COLORSPACE_SRGB, /**< The default colorspace for RGB surfaces if no colorspace is specified */ + SDL_COLORSPACE_YUV_DEFAULT = SDL_COLORSPACE_JPEG /**< The default colorspace for YUV surfaces if no colorspace is specified */ } SDL_Colorspace; - -/* The default colorspace for RGB surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_RGB_DEFAULT SDL_COLORSPACE_SRGB - -/* The default colorspace for YUV surfaces if no colorspace is specified */ -#define SDL_COLORSPACE_YUV_DEFAULT SDL_COLORSPACE_JPEG - /** * A structure that represents a color as RGBA components. * @@ -656,7 +1104,7 @@ typedef enum SDL_Colorspace * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Color { @@ -670,7 +1118,7 @@ typedef struct SDL_Color * The bits of this structure can be directly reinterpreted as a float-packed * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_FColor { @@ -683,7 +1131,7 @@ typedef struct SDL_FColor /** * A set of indexed colors representing a palette. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -698,7 +1146,7 @@ typedef struct SDL_Palette /** * Details about the format of a pixel. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_PixelFormatDetails { @@ -729,7 +1177,7 @@ typedef struct SDL_PixelFormatDetails * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format); @@ -742,16 +1190,16 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat * \param Gmask a pointer filled in with the green mask for the format. * \param Bmask a pointer filled in with the blue mask for the format. * \param Amask a pointer filled in with the alpha mask for the format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatForMasks */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); +extern SDL_DECLSPEC bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask); /** * Convert a bpp value and RGBA masks to an enumerated pixel format. @@ -769,7 +1217,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMasksForPixelFormat */ @@ -788,7 +1236,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format); @@ -804,7 +1252,7 @@ extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDet * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyPalette * \sa SDL_SetPaletteColors @@ -819,15 +1267,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreatePalette(int ncolors); * \param colors an array of SDL_Color structures to copy into the palette. * \param firstcolor the index of the first palette entry to modify. * \param ncolors the number of entries to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors); /** * Free a palette created with SDL_CreatePalette(). @@ -837,7 +1285,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified or destroyed in another thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette */ @@ -872,7 +1320,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette); * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB @@ -911,7 +1359,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -939,7 +1387,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGBA @@ -971,7 +1419,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD * \threadsafety It is safe to call this function from any thread, as long as * the palette is not modified. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPixelFormatDetails * \sa SDL_GetRGB diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h index bfdfa3a..e40f009 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -51,7 +51,7 @@ extern "C" { * \returns the name of the platform. If the correct platform name is not * available, returns a string beginning with the text "Unknown". * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h index e7f91cf..7e9a0a9 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_platform_defines.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -29,180 +29,450 @@ #define SDL_platform_defines_h_ #ifdef _AIX -#define SDL_PLATFORM_AIX 1 + +/** + * A preprocessor macro that is only defined if compiling for AIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_AIX 1 #endif + #ifdef __HAIKU__ -#define SDL_PLATFORM_HAIKU 1 + +/** + * A preprocessor macro that is only defined if compiling for Haiku OS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HAIKU 1 #endif + #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__) -#define SDL_PLATFORM_BSDI 1 + +/** + * A preprocessor macro that is only defined if compiling for BSDi + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_BSDI 1 #endif + #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__) + +/** + * A preprocessor macro that is only defined if compiling for FreeBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_FREEBSD 1 #endif + #if defined(hpux) || defined(__hpux) || defined(__hpux__) -#define SDL_PLATFORM_HPUX 1 + +/** + * A preprocessor macro that is only defined if compiling for HP-UX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_HPUX 1 #endif + #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE) -#define SDL_PLATFORM_IRIX 1 + +/** + * A preprocessor macro that is only defined if compiling for IRIX. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_IRIX 1 #endif + #if (defined(linux) || defined(__linux) || defined(__linux__)) -#define SDL_PLATFORM_LINUX 1 + +/** + * A preprocessor macro that is only defined if compiling for Linux. + * + * Note that Android, although ostensibly a Linux-based system, will not + * define this. It defines SDL_PLATFORM_ANDROID instead. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_LINUX 1 #endif + #if defined(ANDROID) || defined(__ANDROID__) -#undef SDL_PLATFORM_LINUX /* do we need to do this? */ -#define SDL_PLATFORM_ANDROID 1 -#endif -#ifdef __NGAGE__ -#define SDL_PLATFORM_NGAGE 1 + +/** + * A preprocessor macro that is only defined if compiling for Android. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_ANDROID 1 +#undef SDL_PLATFORM_LINUX #endif #if defined(__unix__) || defined(__unix) || defined(unix) -#define SDL_PLATFORM_UNIX 1 + +/** + * A preprocessor macro that is only defined if compiling for a Unix-like + * system. + * + * Other platforms, like Linux, might define this in addition to their primary + * define. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_UNIX 1 #endif #ifdef __APPLE__ -#define SDL_PLATFORM_APPLE 1 + +/** + * A preprocessor macro that is only defined if compiling for Apple platforms. + * + * iOS, macOS, etc will additionally define a more specific platform macro. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_MACOS + * \sa SDL_PLATFORM_IOS + * \sa SDL_PLATFORM_TVOS + * \sa SDL_PLATFORM_VISIONOS + */ +#define SDL_PLATFORM_APPLE 1 + /* lets us know what version of macOS we're compiling on */ #include #ifndef __has_extension /* Older compilers don't support this */ -#define __has_extension(x) 0 -#include -#undef __has_extension + #define __has_extension(x) 0 + #include + #undef __has_extension #else -#include + #include #endif /* Fix building with older SDKs that don't define these - See this for more information: - https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets + See this for more information: + https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets */ #ifndef TARGET_OS_MACCATALYST -#define TARGET_OS_MACCATALYST 0 + #define TARGET_OS_MACCATALYST 0 #endif #ifndef TARGET_OS_IOS -#define TARGET_OS_IOS 0 + #define TARGET_OS_IOS 0 #endif #ifndef TARGET_OS_IPHONE -#define TARGET_OS_IPHONE 0 + #define TARGET_OS_IPHONE 0 #endif #ifndef TARGET_OS_TV -#define TARGET_OS_TV 0 + #define TARGET_OS_TV 0 #endif #ifndef TARGET_OS_SIMULATOR -#define TARGET_OS_SIMULATOR 0 + #define TARGET_OS_SIMULATOR 0 #endif #ifndef TARGET_OS_VISION -#define TARGET_OS_VISION 0 + #define TARGET_OS_VISION 0 #endif #if TARGET_OS_TV -#define SDL_PLATFORM_TVOS 1 + +/** + * A preprocessor macro that is only defined if compiling for tvOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_TVOS 1 #endif + #if TARGET_OS_VISION + +/** + * A preprocessor macro that is only defined if compiling for VisionOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ #define SDL_PLATFORM_VISIONOS 1 #endif + #if TARGET_OS_IPHONE -#define SDL_PLATFORM_IOS 1 + +/** + * A preprocessor macro that is only defined if compiling for iOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_IOS 1 + #else -#define SDL_PLATFORM_MACOS 1 + +/** + * A preprocessor macro that is only defined if compiling for macOS. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_APPLE + */ +#define SDL_PLATFORM_MACOS 1 + #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070 -# error SDL for macOS only supports deploying on 10.7 and above. + #error SDL for macOS only supports deploying on 10.7 and above. #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */ #endif /* TARGET_OS_IPHONE */ -#endif /* defined(SDL_PLATFORM_APPLE) */ +#endif /* defined(__APPLE__) */ #ifdef __EMSCRIPTEN__ + +/** + * A preprocessor macro that is only defined if compiling for Emscripten. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_EMSCRIPTEN 1 #endif + #ifdef __NetBSD__ + +/** + * A preprocessor macro that is only defined if compiling for NetBSD. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_NETBSD 1 #endif + #ifdef __OpenBSD__ -#define SDL_PLATFORM_OPENBSD 1 + +/** + * A preprocessor macro that is only defined if compiling for OpenBSD. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OPENBSD 1 #endif + #if defined(__OS2__) || defined(__EMX__) -#define SDL_PLATFORM_OS2 1 + +/** + * A preprocessor macro that is only defined if compiling for OS/2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OS2 1 #endif + #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE) -#define SDL_PLATFORM_OSF 1 + +/** + * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1). + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_OSF 1 #endif + #ifdef __QNXNTO__ + +/** + * A preprocessor macro that is only defined if compiling for QNX Neutrino. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_QNXNTO 1 #endif + #if defined(riscos) || defined(__riscos) || defined(__riscos__) + +/** + * A preprocessor macro that is only defined if compiling for RISC OS. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_RISCOS 1 #endif + #if defined(__sun) && defined(__SVR4) -#define SDL_PLATFORM_SOLARIS 1 + +/** + * A preprocessor macro that is only defined if compiling for SunOS/Solaris. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_SOLARIS 1 #endif #if defined(__CYGWIN__) + +/** + * A preprocessor macro that is only defined if compiling for Cygwin. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_CYGWIN 1 #endif #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) -#define SDL_PLATFORM_WINDOWS 1 /* Win32 api and Windows-based OSs */ + +/** + * A preprocessor macro that is only defined if compiling for Windows. + * + * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT, + * etc. Each will have their own more-specific platform macros, too. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PLATFORM_WIN32 + * \sa SDL_PLATFORM_XBOXONE + * \sa SDL_PLATFORM_XBOXSERIES + * \sa SDL_PLATFORM_WINGDK + * \sa SDL_PLATFORM_GDK + */ +#define SDL_PLATFORM_WINDOWS 1 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */ #if defined(_MSC_VER) && defined(__has_include) -#if __has_include() -#define HAVE_WINAPIFAMILY_H 1 -#else -#define HAVE_WINAPIFAMILY_H 0 -#endif + #if __has_include() + #define HAVE_WINAPIFAMILY_H 1 + #else + #define HAVE_WINAPIFAMILY_H 0 + #endif -/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ + /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */ #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_) /* _MSC_VER == 1700 for Visual Studio 2012 */ -#define HAVE_WINAPIFAMILY_H 1 + #define HAVE_WINAPIFAMILY_H 1 #else -#define HAVE_WINAPIFAMILY_H 0 + #define HAVE_WINAPIFAMILY_H 0 #endif #if HAVE_WINAPIFAMILY_H -#include -#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) + #include + #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)) #else -#define WINAPI_FAMILY_WINRT 0 + #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ -#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif defined(HAVE_WINAPIFAMILY_H) && HAVE_WINAPIFAMILY_H + #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else -#define SDL_WINAPI_FAMILY_PHONE 0 + #define SDL_WINAPI_FAMILY_PHONE 0 #endif #if WINAPI_FAMILY_WINRT -#define SDL_PLATFORM_WINRT 1 +#error Windows RT/UWP is no longer supported in SDL + #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */ + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK + * for Windows. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_WINGDK 1 + #elif defined(_GAMING_XBOX_XBOXONE) -#define SDL_PLATFORM_XBOXONE 1 + +/** + * A preprocessor macro that is only defined if compiling for Xbox One. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_XBOXONE 1 + #elif defined(_GAMING_XBOX_SCARLETT) + +/** + * A preprocessor macro that is only defined if compiling for Xbox Series. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_PLATFORM_XBOXSERIES 1 + #else -#define SDL_PLATFORM_WIN32 1 + +/** + * A preprocessor macro that is only defined if compiling for desktop Windows. + * + * Despite the "32", this also covers 64-bit Windows; as an informal + * convention, its system layer tends to still be referred to as "the Win32 + * API." + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_WIN32 1 + #endif -#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ +#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */ + /* This is to support generic "any GDK" separate from a platform-specific GDK */ #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES) -#define SDL_PLATFORM_GDK 1 + +/** + * A preprocessor macro that is only defined if compiling for Microsoft GDK on + * any platform. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_GDK 1 #endif + #if defined(__PSP__) || defined(__psp__) -#define SDL_PLATFORM_PSP 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PSP. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PSP 1 #endif + #if defined(__PS2__) || defined(PS2) -#define SDL_PLATFORM_PS2 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony PlayStation + * 2. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_PS2 1 #endif #if defined(__vita__) || defined(__psp2__) -#define SDL_PLATFORM_VITA 1 + +/** + * A preprocessor macro that is only defined if compiling for Sony Vita. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_VITA 1 #endif #ifdef __3DS__ + +/** + * A preprocessor macro that is only defined if compiling for Nintendo 3DS. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PLATFORM_3DS 1 + #undef __3DS__ -#define SDL_PLATFORM_3DS 1 #endif #endif /* SDL_platform_defines_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h index 1fdef78..4056ce3 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_power.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,15 @@ * # CategoryPower * * SDL power management routines. + * + * There is a single function in this category: SDL_GetPowerInfo(). + * + * This function is useful for games on the go. This allows an app to know if + * it's running on a draining battery, which can be useful if the app wants to + * reduce processing, or perhaps framerate, to extend the duration of the + * battery's charge. Perhaps the app just wants to show a battery meter when + * fullscreen, or alert the user when the power is getting extremely low, so + * they can save their game. */ #include @@ -42,7 +51,7 @@ extern "C" { * * These are results returned by SDL_GetPowerInfo(). * - * \since This enum is available since SDL 3.0.0 + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PowerState { @@ -80,7 +89,7 @@ typedef enum SDL_PowerState * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_process.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_process.h new file mode 100644 index 0000000..2cc7739 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_process.h @@ -0,0 +1,430 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryProcess + * + * Process control support. + * + * These functions provide a cross-platform way to spawn and manage OS-level + * processes. + * + * You can create a new subprocess with SDL_CreateProcess() and optionally + * read and write to it using SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). If more advanced functionality like chaining input + * between processes is necessary, you can use + * SDL_CreateProcessWithProperties(). + * + * You can get the status of a created process with SDL_WaitProcess(), or + * terminate the process with SDL_KillProcess(). + * + * Don't forget to call SDL_DestroyProcess() to clean up, whether the process + * process was killed, terminated on its own, or is still running! + */ + +#ifndef SDL_process_h_ +#define SDL_process_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + */ +typedef struct SDL_Process SDL_Process; + +/** + * Create a new process. + * + * The path to the executable is supplied in args[0]. args[1..N] are + * additional arguments passed on the command line of the new process, and the + * argument list should be terminated with a NULL, e.g.: + * + * ```c + * const char *args[] = { "myprogram", "argument", NULL }; + * ``` + * + * Setting pipe_stdio to true is equivalent to setting + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` to `SDL_PROCESS_STDIO_APP`, and + * will allow the use of SDL_ReadProcess() or SDL_GetProcessInput() and + * SDL_GetProcessOutput(). + * + * See SDL_CreateProcessWithProperties() for more details. + * + * \param args the path and arguments for the new process. + * \param pipe_stdio true to create pipes to the process's standard input and + * from the process's standard output, false for the process + * to have no input and inherit the application's standard + * output. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcess(const char * const *args, bool pipe_stdio); + +/** + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + */ +typedef enum SDL_ProcessIO +{ + SDL_PROCESS_STDIO_INHERITED, /**< The I/O stream is inherited from the application. */ + SDL_PROCESS_STDIO_NULL, /**< The I/O stream is ignored. */ + SDL_PROCESS_STDIO_APP, /**< The I/O stream is connected to a new SDL_IOStream that the application can read or write */ + SDL_PROCESS_STDIO_REDIRECT /**< The I/O stream is redirected to an existing SDL_IOStream. */ +} SDL_ProcessIO; + +/** + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER`: an SDL_Environment + * pointer. If this property is set, it will be the entire environment for + * the process, otherwise the current environment is used. + * - `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER`: an SDL_ProcessIO value describing + * where standard input for the process comes from, defaults to + * `SDL_PROCESS_STDIO_NULL`. + * - `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`: an SDL_IOStream pointer used for + * standard input when `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER`: an SDL_ProcessIO value + * describing where standard output for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`: an SDL_IOStream pointer used + * for standard output when `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` is set + * to `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER`: an SDL_ProcessIO value + * describing where standard error for the process goes go, defaults to + * `SDL_PROCESS_STDIO_INHERITED`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_POINTER`: an SDL_IOStream pointer used + * for standard error when `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set to + * `SDL_PROCESS_STDIO_REDIRECT`. + * - `SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN`: true if the error + * output of the process should be redirected into the standard output of + * the process. This property has no effect if + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` is set. + * - `SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN`: true if the process should + * run in the background. In this case the default input and output is + * `SDL_PROCESS_STDIO_NULL` and the exitcode of the process is not + * available, and will always be 0. + * + * On POSIX platforms, wait() and waitpid(-1, ...) should not be called, and + * SIGCHLD should not be ignored or handled because those would prevent SDL + * from properly tracking the lifetime of the underlying process. You should + * use SDL_WaitProcess() instead. + * + * \param props the properties to use. + * \returns the newly created and running process, or NULL if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC SDL_Process *SDLCALL SDL_CreateProcessWithProperties(SDL_PropertiesID props); + +#define SDL_PROP_PROCESS_CREATE_ARGS_POINTER "SDL.process.create.args" +#define SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER "SDL.process.create.environment" +#define SDL_PROP_PROCESS_CREATE_STDIN_NUMBER "SDL.process.create.stdin_option" +#define SDL_PROP_PROCESS_CREATE_STDIN_POINTER "SDL.process.create.stdin_source" +#define SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER "SDL.process.create.stdout_option" +#define SDL_PROP_PROCESS_CREATE_STDOUT_POINTER "SDL.process.create.stdout_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_NUMBER "SDL.process.create.stderr_option" +#define SDL_PROP_PROCESS_CREATE_STDERR_POINTER "SDL.process.create.stderr_source" +#define SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN "SDL.process.create.stderr_to_stdout" +#define SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN "SDL.process.create.background" + +/** + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + */ +extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetProcessProperties(SDL_Process *process); + +#define SDL_PROP_PROCESS_PID_NUMBER "SDL.process.pid" +#define SDL_PROP_PROCESS_STDIN_POINTER "SDL.process.stdin" +#define SDL_PROP_PROCESS_STDOUT_POINTER "SDL.process.stdout" +#define SDL_PROP_PROCESS_STDERR_POINTER "SDL.process.stderr" +#define SDL_PROP_PROCESS_BACKGROUND_BOOLEAN "SDL.process.background" + +/** + * Read all the output from a process. + * + * If a process was created with I/O enabled, you can use this function to + * read the output. This function blocks until the process is complete, + * capturing all output, and providing the process exit code. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param process The process to read. + * \param datasize a pointer filled in with the number of bytes read, may be + * NULL. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns the data or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC void * SDLCALL SDL_ReadProcess(SDL_Process *process, size_t *datasize, int *exitcode); + +/** + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessInput(SDL_Process *process); + +/** + * Get the SDL_IOStream associated with process standard output. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Reading from this stream can return 0 with SDL_GetIOStatus() returning + * SDL_IO_STATUS_NOT_READY if no output is available yet. + * + * \param process The process to get the output stream for. + * \returns the output stream or NULL on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + */ +extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_GetProcessOutput(SDL_Process *process); + +/** + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_KillProcess(SDL_Process *process, bool force); + +/** + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a pointer filled in with the process exit code if the + * process has exited, may be NULL. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + */ +extern SDL_DECLSPEC bool SDLCALL SDL_WaitProcess(SDL_Process *process, bool block, int *exitcode); + +/** + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyProcess(SDL_Process *process); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_process_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h index c3a2c82..1f47d5f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_properties.h @@ -1,6 +1,6 @@ /* - Simple DiretMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -61,14 +61,14 @@ extern "C" { /** * SDL properties ID * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_PropertiesID; /** * SDL property type * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_PropertyType { @@ -86,7 +86,7 @@ typedef enum SDL_PropertyType * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); @@ -100,7 +100,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyProperties */ @@ -116,14 +116,14 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); * * \param src the properties to copy. * \param dst the destination properties. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** * Lock a group of properties. @@ -138,16 +138,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SD * thread. * * \param props the properties to lock. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_UnlockProperties */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); +extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** * Unlock a group of properties. @@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockProperties(SDL_PropertiesID props); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockProperties */ @@ -180,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); * \threadsafety This callback may fire without any locks held; if this is a * concern, the app should provide its own locking. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetPointerPropertyWithCleanup */ @@ -204,18 +204,18 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value) * \param cleanup the function to call when this property is deleted, or NULL * if no cleanup is necessary. * \param userdata a pointer that is passed to the cleanup function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_SetPointerProperty * \sa SDL_CleanupPropertyCallback */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata); /** * Set a pointer property in a group of properties. @@ -223,12 +223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPointerProperty * \sa SDL_HasProperty @@ -238,7 +238,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Prope * \sa SDL_SetPointerPropertyWithCleanup * \sa SDL_SetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value); /** * Set a string property in a group of properties. @@ -249,16 +249,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID pro * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property, or NULL to delete the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStringProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** * Set an integer property in a group of properties. @@ -266,16 +266,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumberProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** * Set a floating point property in a group of properties. @@ -283,16 +283,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID prop * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetFloatProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** * Set a boolean property in a group of properties. @@ -300,31 +300,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props * \param props the properties to modify. * \param name the name of the property to modify. * \param value the new value of the property. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value); +extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value); /** * Return whether a property exists in a group of properties. * * \param props the properties to query. * \param name the name of the property to query. - * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't. + * \returns true if the property exists, or false if it doesn't. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** * Get the type of a property in a group of properties. @@ -336,7 +336,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasProperty */ @@ -363,7 +363,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetBooleanProperty * \sa SDL_GetFloatProperty @@ -391,7 +391,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props * If you need to avoid this, use SDL_LockProperties() and * SDL_UnlockProperties(). * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -413,7 +413,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -435,7 +435,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty @@ -457,27 +457,27 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPropertyType * \sa SDL_HasProperty * \sa SDL_SetBooleanProperty */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); +extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value); /** * Clear a property from a group of properties. * * \param props the properties to modify. * \param name the name of the property to clear. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); /** * A callback used to enumerate all the properties in a group of properties. @@ -492,7 +492,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, c * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this * callback. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EnumerateProperties */ @@ -507,14 +507,14 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop * \param props the properties to query. * \param callback the function to call for each property. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** * Destroy a group of properties. @@ -528,7 +528,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID pr * locked or other threads might be setting or getting values * from these properties. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h index ea97df9..8998de6 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_rect.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,7 +23,7 @@ * # CategoryRect * * Some helper functions for managing rectangles and 2D points, in both - * interger and floating point versions. + * integer and floating point versions. */ #ifndef SDL_rect_h_ @@ -41,7 +41,7 @@ extern "C" { /** * The structure that defines a point (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect @@ -55,7 +55,7 @@ typedef struct SDL_Point /** * The structure that defines a point (using floating point values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat @@ -70,7 +70,7 @@ typedef struct SDL_FPoint /** * A rectangle, with the origin at the upper left (using integers). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmpty * \sa SDL_RectsEqual @@ -91,7 +91,7 @@ typedef struct SDL_Rect * A rectangle, with the origin at the upper left (using floating point * values). * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -121,7 +121,7 @@ typedef struct SDL_FRect * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) { @@ -146,16 +146,16 @@ SDL_FORCE_INLINE void SDL_RectToFRect(const SDL_Rect *rect, SDL_FRect *frect) * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) { return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) && - (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? true : false; } /** @@ -170,15 +170,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r) * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) +SDL_FORCE_INLINE bool SDL_RectEmpty(const SDL_Rect *r) { - return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w <= 0) || (r->h <= 0)) ? true : false; } /** @@ -194,51 +194,51 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r) * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) +SDL_FORCE_INLINE bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b) { return (a && b && (a->x == b->x) && (a->y == b->y) && - (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE; + (a->w == b->w) && (a->h == b->h)) ? true : false; } /** * Determine whether two rectangles intersect. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B); /** * Calculate the intersection of two rectangles. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_Rect structure representing the first rectangle. * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate the union of two rectangles. @@ -247,12 +247,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, * \param B an SDL_Rect structure representing the second rectangle. * \param result an SDL_Rect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); /** * Calculate a minimal rectangle enclosing a set of points. @@ -266,12 +266,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const S * \param clip an SDL_Rect used for clipping or NULL to enclose all points. * \param result an SDL_Rect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); /** * Calculate the intersection of a rectangle and line segment. @@ -287,11 +287,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); /* SDL_FRect versions... */ @@ -311,16 +311,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Re * * \param p the point to test. * \param r the rectangle to test. - * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise. + * \returns true if `p` is contained by `r`, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r) { return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) && - (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE; + (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? true : false; } /** @@ -335,15 +335,15 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FR * be able to find this function inside SDL itself). * * \param r the rectangle to test. - * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise. + * \returns true if the rectangle is "empty", false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) +SDL_FORCE_INLINE bool SDL_RectEmptyFloat(const SDL_FRect *r) { - return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE; + return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? true : false; } /** @@ -363,22 +363,22 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r) * \param a the first rectangle to test. * \param b the second rectangle to test. * \param epsilon the epsilon value for comparison. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualFloat */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) +SDL_FORCE_INLINE bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon) { return (a && b && ((a == b) || ((SDL_fabsf(a->x - b->x) <= epsilon) && (SDL_fabsf(a->y - b->y) <= epsilon) && (SDL_fabsf(a->w - b->w) <= epsilon) && (SDL_fabsf(a->h - b->h) <= epsilon)))) - ? SDL_TRUE : SDL_FALSE; + ? true : false; } /** @@ -398,15 +398,15 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR * * \param a the first rectangle to test. * \param b the second rectangle to test. - * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise. + * \returns true if the rectangles are equal, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RectsEqualEpsilon */ -SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) +SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b) { return SDL_RectsEqualEpsilon(a, b, SDL_FLT_EPSILON); } @@ -414,34 +414,34 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRec /** * Determine whether two rectangles intersect with float precision. * - * If either pointer is NULL the function will return SDL_FALSE. + * If either pointer is NULL the function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); +extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B); /** * Calculate the intersection of two rectangles with float precision. * - * If `result` is NULL then this function will return SDL_FALSE. + * If `result` is NULL then this function will return false. * * \param A an SDL_FRect structure representing the first rectangle. * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the intersection of * rectangles `A` and `B`. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersectionFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate the union of two rectangles with float precision. @@ -450,12 +450,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRec * \param B an SDL_FRect structure representing the second rectangle. * \param result an SDL_FRect structure filled in with the union of rectangles * `A` and `B`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); /** * Calculate a minimal rectangle enclosing a set of points with float @@ -470,12 +470,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, c * \param clip an SDL_FRect used for clipping or NULL to enclose all points. * \param result an SDL_FRect structure filled in with the minimal enclosing * rectangle. - * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the - * points were outside of the clipping rectangle. + * \returns true if any points were enclosed or false if all the points were + * outside of the clipping rectangle. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); /** * Calculate the intersection of a rectangle and line segment with float @@ -492,11 +492,11 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_F * \param Y1 a pointer to the starting Y-coordinate of the line. * \param X2 a pointer to the ending X-coordinate of the line. * \param Y2 a pointer to the ending Y-coordinate of the line. - * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise. + * \returns true if there is an intersection, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h index 706308c..891e994 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_render.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -40,8 +40,8 @@ * * This API is designed to accelerate simple 2D operations. You may want more * functionality such as polygons and particle effects and in that case you - * should use SDL's OpenGL/Direct3D support or one of the many good 3D - * engines. + * should use SDL's OpenGL/Direct3D support, the SDL3 GPU API, or one of the + * many good 3D engines. * * These functions must be called from the main thread. See this bug for * details: https://github.com/libsdl-org/SDL/issues/986 @@ -51,10 +51,13 @@ #define SDL_render_h_ #include +#include #include #include +#include #include #include +#include #include #include @@ -66,14 +69,14 @@ extern "C" { /** * The name of the software renderer. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_SOFTWARE_RENDERER "software" /** * Vertex structure. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Vertex { @@ -85,7 +88,7 @@ typedef struct SDL_Vertex /** * The access pattern allowed for a texture. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_TextureAccess { @@ -97,7 +100,7 @@ typedef enum SDL_TextureAccess /** * How the logical size is mapped to the output. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_RendererLogicalPresentation { @@ -111,15 +114,32 @@ typedef enum SDL_RendererLogicalPresentation /** * A structure representing rendering state * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Renderer SDL_Renderer; +#ifndef SDL_INTERNAL + /** * An efficient driver-specific representation of pixel data * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateTexture + * \sa SDL_CreateTextureFromSurface + * \sa SDL_CreateTextureWithProperties + * \sa SDL_DestroyTexture */ +struct SDL_Texture +{ + SDL_PixelFormat format; /**< The format of the texture, read-only */ + int w; /**< The width of the texture, read-only. */ + int h; /**< The height of the texture, read-only. */ + + int refcount; /**< Application reference count, used when freeing texture */ +}; +#endif /* !SDL_INTERNAL */ + typedef struct SDL_Texture SDL_Texture; /* Function prototypes */ @@ -135,7 +155,9 @@ typedef struct SDL_Texture SDL_Texture; * * \returns the number of built in render drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_GetRenderDriver @@ -158,7 +180,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * \returns the name of the rendering driver at the requested index, or NULL * if an invalid index was specified. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumRenderDrivers */ @@ -174,36 +198,43 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index); * SDL_CreateWindow()). * \param window a pointer filled with the window, or NULL on error. * \param renderer a pointer filled with the renderer, or NULL on error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer); /** * Create a 2D rendering context for a window. * * If you want a specific renderer, you can specify its name here. A list of - * available renderers can be obtained by calling SDL_GetRenderDriver multiple - * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't - * need a specific renderer, specify NULL and SDL will attempt to choose the - * best option for you, based on what is available on the user's system. + * available renderers can be obtained by calling SDL_GetRenderDriver() + * multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you + * don't need a specific renderer, specify NULL and SDL will attempt to choose + * the best option for you, based on what is available on the user's system. + * + * If `name` is a comma-separated list, SDL will try each name, in the order + * listed, until one succeeds or all of them fail. * * By default the rendering size matches the window size in pixels, but you * can call SDL_SetRenderLogicalPresentation() to change the content size and * scaling options. * * \param window the window where rendering is displayed. - * \param name the name of the rendering driver to initialize, or NULL to - * initialize the first one supporting the requested flags. + * \param name the name of the rendering driver to initialize, or NULL to let + * SDL choose one. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRendererWithProperties * \sa SDL_CreateSoftwareRenderer @@ -225,7 +256,7 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * displayed, required if this isn't a software renderer using a surface * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering * is displayed, if you want a software renderer without a window - * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace + * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace * value describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and @@ -255,7 +286,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateRenderer @@ -290,7 +323,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_ * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyRenderer */ @@ -303,7 +338,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surfac * \returns the rendering context on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); @@ -314,7 +351,9 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window *window); * \returns the window on success or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer); @@ -325,7 +364,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende * \returns the name of the selected renderer, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_CreateRendererWithProperties @@ -348,21 +389,21 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) * array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN, * representing the available texture formats for this renderer. - * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the colorspace for output to the display, defaults to * SDL_COLORSPACE_SRGB. * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with * HDR enabled. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is * automatically multiplied into the color scale. This property can change - * dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * dynamically when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range * that can be displayed, in terms of the SDR white point. When HDR is not * enabled, this will be 1.0. This property can change dynamically when - * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent. + * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent. * * With the direct3d renderer: * @@ -403,11 +444,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *rende * swapchain images, or potential frames in flight, used by the Vulkan * renderer * + * With the gpu renderer: + * + * - `SDL_PROP_RENDERER_GPU_DEVICE_POINTER`: the SDL_GPUDevice associated with + * the renderer + * * \param renderer the rendering context. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer); @@ -434,6 +482,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende #define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index" #define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count" +#define SDL_PROP_RENDERER_GPU_DEVICE_POINTER "SDL.renderer.gpu.device" /** * Get the output size in pixels of a rendering context. @@ -444,14 +493,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende * \param renderer the rendering context. * \param w a pointer filled in with the width in pixels. * \param h a pointer filled in with the height in pixels. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Get the current output size in pixels of a rendering context. @@ -464,28 +515,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *rende * \param renderer the rendering context. * \param w a pointer filled in with the current width. * \param h a pointer filled in with the current height. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h); /** * Create a texture for a rendering context. * + * The contents of a texture when first created are not defined. + * * \param renderer the rendering context. * \param format one of the enumerated values in SDL_PixelFormat. * \param access one of the enumerated values in SDL_TextureAccess. * \param w the width of the texture in pixels. * \param h the height of the texture in pixels. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTextureFromSurface * \sa SDL_CreateTextureWithProperties @@ -513,7 +569,9 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer *render * \returns the created texture or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureWithProperties @@ -526,7 +584,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * These are the supported properties: * - * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_ColorSpace value + * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_Colorspace value * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures, * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for @@ -617,11 +675,12 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Rende * * \param renderer the rendering context. * \param props the properties to use. - * \returns a pointer to the created texture or NULL if no rendering context - * was active, the format was unsupported, or the width or height - * were out of range; call SDL_GetError() for more information. + * \returns the created texture or NULL on failure; call SDL_GetError() for + * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateTexture @@ -661,7 +720,7 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * The following read-only properties are provided by SDL: * - * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing + * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_Colorspace value describing * the texture colorspace. * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in * SDL_PixelFormat. @@ -701,14 +760,8 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * * With the vulkan renderer: * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_POINTER`: the VkImage associated with - * the texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_U_POINTER`: the VkImage associated with - * the U plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_V_POINTER`: the VkImage associated with - * the V plane of a YUV texture - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_UV_POINTER`: the VkImage associated with - * the UV plane of a NV12/NV21 texture + * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the + * texture * * With the opengl renderer: * @@ -740,16 +793,13 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureWithProperties(SDL_Re * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc) * - * With the vulkan renderer: - * - * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the - * texture - * * \param texture the texture to query. * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture); @@ -789,7 +839,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Textur * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture); @@ -801,12 +851,14 @@ extern SDL_DECLSPEC SDL_Renderer * SDLCALL SDL_GetRendererFromTexture(SDL_Textur * argument can be NULL if you don't need this information. * \param h a pointer filled in with the height of the texture in pixels. This * argument can be NULL if you don't need this information. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, float *w, float *h); /** * Set an additional color value multiplied into render copy operations. @@ -818,22 +870,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureSize(SDL_Texture *texture, fl * `srcC = srcC * (color / 255)` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b); /** @@ -846,22 +900,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture * `srcC = srcC * color` * * Color modulation is not always supported by the renderer; it will return - * SDL_FALSE if color modulation is not supported. + * false if color modulation is not supported. * * \param texture the texture to update. * \param r the red color value multiplied into copy operations. * \param g the green color value multiplied into copy operations. * \param b the blue color value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b); /** @@ -871,16 +927,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *te * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b); /** * Get the additional color value multiplied into render copy operations. @@ -889,16 +947,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b); /** * Set an additional alpha value multiplied into render copy operations. @@ -909,20 +969,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *te * `srcA = srcA * (alpha / 255)` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_SetTextureAlphaModFloat * \sa SDL_SetTextureColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha); /** * Set an additional alpha value multiplied into render copy operations. @@ -933,83 +995,93 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture * `srcA = srcA * alpha` * * Alpha modulation is not always supported by the renderer; it will return - * SDL_FALSE if alpha modulation is not supported. + * false if alpha modulation is not supported. * * \param texture the texture to update. * \param alpha the source alpha value multiplied into copy operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_SetTextureAlphaMod * \sa SDL_SetTextureColorModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaModFloat * \sa SDL_GetTextureColorMod * \sa SDL_SetTextureAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha); /** * Get the additional alpha value multiplied into render copy operations. * * \param texture the texture to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureAlphaMod * \sa SDL_GetTextureColorModFloat * \sa SDL_SetTextureAlphaModFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha); /** * Set the blend mode for a texture, used by SDL_RenderTexture(). * * If the blend mode is not supported, the closest supported mode is chosen - * and this function returns -1. + * and this function returns false. * * \param texture the texture to update. * \param blendMode the SDL_BlendMode to use for texture blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode); /** * Get the blend mode used for texture copy operations. * * \param texture the texture to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode); /** * Set the scale mode used for texture scale operations. @@ -1020,28 +1092,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureBlendMode(SDL_Texture *textur * * \param texture the texture to update. * \param scaleMode the SDL_ScaleMode to use for texture scaling. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode); /** * Get the scale mode used for texture scale operations. * * \param texture the texture to query. * \param scaleMode a pointer filled in with the current scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTextureScaleMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode); /** * Update the given texture rectangle with new pixel data. @@ -1063,17 +1139,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureScaleMode(SDL_Texture *textur * \param pixels the raw pixel data in the format of the texture. * \param pitch the number of bytes in a row of pixel data, including padding * between lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture * \sa SDL_UpdateNVTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch); /** * Update a rectangle within a planar YV12 or IYUV texture with new pixel @@ -1095,15 +1173,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateTexture(SDL_Texture *texture, con * \param Vplane the raw pixel data for the V plane. * \param Vpitch the number of bytes between rows of pixel data for the V * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateNVTexture * \sa SDL_UpdateTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, @@ -1125,15 +1205,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture, * \param UVplane the raw pixel data for the UV plane. * \param UVpitch the number of bytes between rows of pixel data for the UV * plane. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_UpdateTexture * \sa SDL_UpdateYUVTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch); @@ -1157,16 +1239,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture, * appropriately offset by the locked area. * \param pitch this is filled in with the pitch of the locked pixels; the * pitch is the length of one row in bytes. - * \returns SDL_TRUE on success or SDL_FALSE if the texture is not valid or - * was not created with `SDL_TEXTUREACCESS_STREAMING`; call - * SDL_GetError() for more information. + * \returns true on success or false if the texture is not valid or was not + * created with `SDL_TEXTUREACCESS_STREAMING`; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTextureToSurface * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch); @@ -1192,17 +1276,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTexture(SDL_Texture *texture, * `SDL_TEXTUREACCESS_STREAMING`. * \param rect a pointer to the rectangle to lock for access. If the rect is * NULL, the entire texture will be locked. - * \param surface this is filled in with an SDL surface representing the - * locked area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param surface a pointer to an SDL surface of size **rect**. Don't assume + * any specific pixel content. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture * \sa SDL_UnlockTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface); /** * Unlock a texture, uploading the changes to video memory, if needed. @@ -1217,7 +1303,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockTextureToSurface(SDL_Texture *textu * * \param texture a texture locked by SDL_LockTexture(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockTexture */ @@ -1234,14 +1322,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture); * \param texture the targeted texture, which must be created with the * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the * window instead of a texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderTarget */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture); /** * Get the current render target. @@ -1252,7 +1342,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * \param renderer the rendering context. * \returns the current render target or NULL for the default render target. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderTarget */ @@ -1261,13 +1353,23 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend /** * Set a device independent resolution and presentation mode for rendering. * - * This function sets the width and height of the logical rendering output. A - * render target is created at the specified size and used for rendering and - * then copied to the output during presentation. + * This function sets the width and height of the logical rendering output. + * The renderer will act as if the window is always the requested dimensions, + * scaling to the actual window resolution as necessary. + * + * This can be useful for games that expect a fixed size, but would like to + * scale the output to whatever is available, regardless of how a user resizes + * a window, or if the display is high DPI. * * You can disable logical coordinates by setting the mode to * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel - * resolution of the output window. + * resolution of the output window; it is safe to toggle logical presentation + * during the rendering of a frame: perhaps most of the rendering is done to + * specific dimensions but to make fonts look sharp, the app turns off logical + * presentation while drawing text. + * + * Letterboxing will only happen if logical presentation is enabled during + * SDL_RenderPresent; be sure to reenable it first if you were using it. * * You can convert coordinates in an event into rendering coordinates using * SDL_ConvertEventToRenderCoordinates(). @@ -1276,17 +1378,18 @@ extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *rend * \param w the width of the logical resolution. * \param h the height of the logical resolution. * \param mode the presentation mode used. - * \param scale_mode the scale mode used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertEventToRenderCoordinates * \sa SDL_GetRenderLogicalPresentation * \sa SDL_GetRenderLogicalPresentationRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode); /** * Get device independent resolution and presentation mode for rendering. @@ -1297,16 +1400,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param w an int to be filled with the width. * \param h an int to be filled with the height. - * \param mode a pointer filled in with the presentation mode. - * \param scale_mode a pointer filled in with the scale mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param mode the presentation mode used. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode); /** * Get the final presentation rectangle for rendering. @@ -1319,36 +1423,54 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Render * \param renderer the rendering context. * \param rect a pointer filled in with the final presentation rectangle, may * be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentationRect(SDL_Renderer *renderer, SDL_FRect *rect); /** * Get a point in render coordinates when given a point in window coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param window_x the x coordinate in window coordinates. * \param window_y the y coordinate in window coordinates. * \param x a pointer filled with the x coordinate in render coordinates. * \param y a pointer filled with the y coordinate in render coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y); /** * Get a point in window coordinates when given a point in render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * * \param renderer the rendering context. * \param x the x coordinate in render coordinates. * \param y the y coordinate in render coordinates. @@ -1356,65 +1478,95 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Rendere * coordinates. * \param window_y a pointer filled with the y coordinate in window * coordinates. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderLogicalPresentation * \sa SDL_SetRenderScale + * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y); /** * Convert the coordinates in an event to render coordinates. * + * This takes into account several states: + * + * - The window dimensions. + * - The logical presentation settings (SDL_SetRenderLogicalPresentation) + * - The scale (SDL_SetRenderScale) + * - The viewport (SDL_SetRenderViewport) + * + * Various event types are converted with this function: mouse, touch, pen, + * etc. + * * Touch coordinates are converted from normalized coordinates in the window * to non-normalized rendering coordinates. * - * Once converted, the coordinates may be outside the rendering area. + * Relative mouse coordinates (xrel and yrel event fields) are _also_ + * converted. Applications that do not want these fields converted should use + * SDL_RenderCoordinatesFromWindow() on the specific event fields instead of + * converting the entire event structure. + * + * Once converted, coordinates may be outside the rendering area. * * \param renderer the rendering context. * \param event the event to modify. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderCoordinatesFromWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event); /** * Set the drawing area for rendering on the current target. * + * Drawing will clip to this area (separately from any clipping done with + * SDL_SetRenderClipRect), and the top left of the area will become coordinate + * (0, 0) for future drawing commands. + * + * The area's width and height must be >= 0. + * * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the drawing area, or NULL * to set the viewport to the entire target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_RenderViewportSet */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the drawing area for the current target. * * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current drawing area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderViewportSet * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect); /** * Return whether an explicit rectangle was set as the viewport. @@ -1424,15 +1576,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *rendere * viewport is always reset when changing rendering targets. * * \param renderer the rendering context. - * \returns SDL_TRUE if the viewport was set to a specific rectangle, or - * SDL_FALSE if it was set to NULL (the entire target). + * \returns true if the viewport was set to a specific rectangle, or false if + * it was set to NULL (the entire target). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderViewport * \sa SDL_SetRenderViewport */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer); /** * Get the safe area for rendering within the current viewport. @@ -1447,12 +1601,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect a pointer filled in with the area that is safe for interactive * content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, SDL_Rect *rect); /** * Set the clip rectangle for rendering on the specified target. @@ -1460,15 +1616,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the clip area, relative to * the viewport, or NULL to disable clipping. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_RenderClipEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect); /** * Get the clip rectangle for the current target. @@ -1476,29 +1634,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *rendere * \param renderer the rendering context. * \param rect an SDL_Rect structure filled in with the current clipping area * or an empty rectangle if clipping is disabled. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderClipEnabled * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect); /** * Get whether clipping is enabled on the given renderer. * * \param renderer the rendering context. - * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call - * SDL_GetError() for more information. + * \returns true if clipping is enabled or false if not; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderClipRect * \sa SDL_SetRenderClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer); /** * Set the drawing scale for rendering on the current target. @@ -1514,14 +1676,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *rendere * \param renderer the rendering context. * \param scaleX the horizontal scaling factor. * \param scaleY the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY); /** * Get the drawing scale for the current target. @@ -1529,14 +1693,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, * \param renderer the rendering context. * \param scaleX a pointer filled in with the horizontal scaling factor. * \param scaleY a pointer filled in with the vertical scaling factor. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY); /** * Set the color used for drawing operations. @@ -1551,15 +1717,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, * \param a the alpha value used to draw on the rendering target; usually * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to * specify how the alpha channel is used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColor * \sa SDL_SetRenderDrawColorFloat */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Set the color used for drawing operations (Rect, Line and Clear). @@ -1574,15 +1742,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *render * \param a the alpha value used to draw on the rendering target. Use * SDL_SetRenderDrawBlendMode to specify how the alpha channel is * used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1596,15 +1766,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *r * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target; usually `SDL_ALPHA_OPAQUE` (255). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawColorFloat * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Get the color used for drawing operations (Rect, Line and Clear). @@ -1618,15 +1790,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *render * rendering target. * \param a a pointer filled in with the alpha value used to draw on the * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColorFloat * \sa SDL_GetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a); /** * Set the color scale used for render operations. @@ -1641,28 +1815,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *r * * \param renderer the rendering context. * \param scale the color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale); /** * Get the color scale used for render operations. * * \param renderer the rendering context. * \param scale a pointer filled in with the current color scale value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderColorScale */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale); /** * Set the blend mode used for drawing operations (Fill and Line). @@ -1671,28 +1849,32 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderColorScale(SDL_Renderer *rende * * \param renderer the rendering context. * \param blendMode the SDL_BlendMode to use for blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode); /** * Get the blend mode used for drawing operations. * * \param renderer the rendering context. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode); /** * Clear the current rendering target with the drawing color. @@ -1703,14 +1885,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *re * SDL_SetRenderDrawColor() when needed. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); /** * Draw a point on the current rendering target at subpixel precision. @@ -1718,14 +1902,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderClear(SDL_Renderer *renderer); * \param renderer the renderer which should draw a point. * \param x the x coordinate of the point. * \param y the y coordinate of the point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoints */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y); /** * Draw multiple points on the current rendering target at subpixel precision. @@ -1733,14 +1919,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, flo * \param renderer the renderer which should draw multiple points. * \param points the points to draw. * \param count the number of points to draw. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderPoint */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a line on the current rendering target at subpixel precision. @@ -1750,14 +1938,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, co * \param y1 the y coordinate of the start point. * \param x2 the x coordinate of the end point. * \param y2 the y coordinate of the end point. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLines */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2); /** * Draw a series of connected lines on the current rendering target at @@ -1766,14 +1956,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLine(SDL_Renderer *renderer, floa * \param renderer the renderer which should draw multiple lines. * \param points the points along the lines. * \param count the number of points, drawing count-1 lines. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderLine */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count); /** * Draw a rectangle on the current rendering target at subpixel precision. @@ -1781,14 +1973,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderLines(SDL_Renderer *renderer, con * \param renderer the renderer which should draw a rectangle. * \param rect a pointer to the destination rectangle, or NULL to outline the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Draw some number of rectangles on the current rendering target at subpixel @@ -1797,14 +1991,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRect(SDL_Renderer *renderer, cons * \param renderer the renderer which should draw multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Fill a rectangle on the current rendering target with the drawing color at @@ -1813,14 +2009,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderRects(SDL_Renderer *renderer, con * \param renderer the renderer which should fill a rectangle. * \param rect a pointer to the destination rectangle, or NULL for the entire * rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect); /** * Fill some number of rectangles on the current rendering target with the @@ -1829,14 +2027,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, * \param renderer the renderer which should fill multiple rectangles. * \param rects a pointer to an array of destination rectangles. * \param count the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderFillRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count); /** * Copy a portion of the texture to the current rendering target at subpixel @@ -1848,15 +2048,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, * texture. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTextureRotated * \sa SDL_RenderTextureTiled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect); /** * Copy a portion of the source texture to the current rendering target, with @@ -1875,17 +2077,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, S * around dstrect.w/2, dstrect.h/2). * \param flip an SDL_FlipMode value stating which flipping actions should be * performed on the texture. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, - const double angle, const SDL_FPoint *center, - const SDL_FlipMode flip); + double angle, const SDL_FPoint *center, + SDL_FlipMode flip); + +/** + * Copy a portion of the source texture to the current rendering target, with + * affine transform, at subpixel precision. + * + * \param renderer the renderer which should copy parts of a texture. + * \param texture the source texture. + * \param srcrect a pointer to the source rectangle, or NULL for the entire + * texture. + * \param origin a pointer to a point indicating where the top-left corner of + * srcrect should be mapped to, or NULL for the rendering + * target's origin. + * \param right a pointer to a point indicating where the top-right corner of + * srcrect should be mapped to, or NULL for the rendering + * target's top-right corner. + * \param down a pointer to a point indicating where the bottom-left corner of + * srcrect should be mapped to, or NULL for the rendering target's + * bottom-left corner. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety You may only call this function from the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderTexture + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureAffine(SDL_Renderer *renderer, SDL_Texture *texture, + const SDL_FRect *srcrect, const SDL_FPoint *origin, + const SDL_FPoint *right, const SDL_FPoint *down); /** * Tile a portion of the texture to the current rendering target at subpixel @@ -1903,14 +2137,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureRotated(SDL_Renderer *rend * 64x64 tiles. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float scale, const SDL_FRect *dstrect); /** * Perform a scaled copy using the 9-grid algorithm to the current rendering @@ -1935,14 +2171,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTextureTiled(SDL_Renderer *render * corner of `dstrect`, or 0.0f for an unscaled copy. * \param dstrect a pointer to the destination rectangle, or NULL for the * entire rendering target. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderTexture */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect *dstrect); /** * Render a list of triangles, optionally using a texture and indices into the @@ -1957,14 +2195,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderTexture9Grid(SDL_Renderer *render * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices number of indices. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometryRaw */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices); @@ -1987,14 +2227,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * if NULL all vertices will be rendered in sequential order. * \param num_indices number of indices. * \param size_indices index size: 1 (byte), 2 (short), 4 (int). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RenderGeometry */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, +extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, @@ -2017,7 +2259,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *rendere * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect); @@ -2041,18 +2285,20 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * pixel. * * Please note, that in case of rendering to a texture - there is **no need** - * to call `SDL_RenderPresent` after drawing needed objects to a texture, you - * are only required to change back the rendering target to default via - * `SDL_SetRenderTarget(renderer, NULL)` afterwards, as textures by themselves - * do not have a concept of backbuffers. + * to call `SDL_RenderPresent` after drawing needed objects to a texture, and + * should not be done; you are only required to change back the rendering + * target to default via `SDL_SetRenderTarget(renderer, NULL)` afterwards, as + * textures by themselves do not have a concept of backbuffers. Calling + * SDL_RenderPresent while rendering to a texture will still update the screen + * with any current drawing that has been done _to the window itself_. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \threadsafety You may only call this function on the main thread. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer * \sa SDL_RenderClear @@ -2067,7 +2313,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *ren * \sa SDL_SetRenderDrawBlendMode * \sa SDL_SetRenderDrawColor */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); /** * Destroy the specified texture. @@ -2077,7 +2323,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenderPresent(SDL_Renderer *renderer); * * \param texture the texture to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateTexture * \sa SDL_CreateTextureFromSurface @@ -2092,7 +2340,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture); * * \param renderer the rendering context. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRenderer */ @@ -2122,12 +2372,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer); * be prepared to make changes if specific state needs to be protected. * * \param renderer the rendering context. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); +extern SDL_DECLSPEC bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); /** * Get the CAMetalLayer associated with the given Metal renderer. @@ -2139,7 +2391,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a * Metal renderer. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalCommandEncoder */ @@ -2160,7 +2414,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *rendere * \returns an `id` on success, or NULL if the * renderer isn't a Metal renderer or there was an error. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderMetalLayer */ @@ -2187,15 +2443,15 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer * \param signal_semaphore a VkSempahore that SDL will signal when rendering * for the current frame is complete, or 0 if not * needed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is **NOT** safe to call this function from two threads at * once. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); +extern SDL_DECLSPEC bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore); /** * Toggle VSync of the given renderer. @@ -2204,21 +2460,23 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer * * The `vsync` parameter can be 1 to synchronize present with every vertical * refresh, 2 to synchronize present with every second vertical refresh, etc., - * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), - * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is - * supported by every driver, so you should check the return value to see - * whether the requested setting is supported. + * SDL_RENDERER_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync), or + * SDL_RENDERER_VSYNC_DISABLED to disable. Not every value is supported by + * every driver, so you should check the return value to see whether the + * requested setting is supported. * * \param renderer the renderer to toggle. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync); #define SDL_RENDERER_VSYNC_DISABLED 0 #define SDL_RENDERER_VSYNC_ADAPTIVE (-1) @@ -2229,14 +2487,96 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, * \param renderer the renderer to toggle. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetRenderVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetRenderVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync); + +/** + * The size, in pixels, of a single SDL_RenderDebugText() character. + * + * The font is monospaced and square, so this applies to all characters. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + */ +#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8 + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a string of text to an SDL_Renderer. Note that + * this is a convenience function for debugging, with severe limitations, and + * not intended to be used for production apps and games. + * + * Among these limitations: + * + * - It accepts UTF-8 strings, but will only renders ASCII characters. + * - It has a single, tiny size (8x8 pixels). One can use logical presentation + * or scaling to adjust it, but it will be blurry. + * - It uses a simple, hardcoded bitmap font. It does not allow different font + * selections and it does not support truetype, for proper scaling. + * - It does no word-wrapping and does not treat newline characters as a line + * break. If the text goes out of the window, it's gone. + * + * For serious text rendering, there are several good options, such as + * SDL_ttf, stb_truetype, or other external libraries. + * + * On first use, this will create an internal texture for rendering glyphs. + * This texture will live until the renderer is destroyed. + * + * The text is drawn in the color specified by SDL_SetRenderDrawColor(). + * + * \param renderer the renderer which should draw a line of text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param str the string to render. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugTextFormat + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str); + +/** + * Draw debug text to an SDL_Renderer. + * + * This function will render a printf()-style format string to a renderer. + * Note that this is a convinence function for debugging, with severe + * limitations, and is not intended to be used for production apps and games. + * + * For the full list of limitations and other useful information, see + * SDL_RenderDebugText. + * + * \param renderer the renderer which should draw the text. + * \param x the x coordinate where the top-left corner of the text will draw. + * \param y the y coordinate where the top-left corner of the text will draw. + * \param fmt the format string to draw. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RenderDebugText + * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE + */ +extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugTextFormat(SDL_Renderer *renderer, float x, float y, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(4); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h index f78e5d9..18f7c4d 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_revision.h @@ -1,22 +1,22 @@ /* - Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga - 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. + 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: + 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. + 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. */ /* WIKI CATEGORY: Version */ @@ -48,9 +48,9 @@ */ #define SDL_REVISION "Some arbitrary string decided at SDL build time" #elif defined(SDL_VENDOR_INFO) -#define SDL_REVISION SDL_VENDOR_INFO +#define SDL_REVISION "release-3.2.0-0-g535d80bad (" SDL_VENDOR_INFO ")" #else -#define SDL_REVISION "" +#define SDL_REVISION "release-3.2.0-0-g535d80bad" #endif #endif /* SDL_revision_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h index ccf8bb5..9650a6c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_scancode.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,11 @@ * # CategoryScancode * * Defines keyboard scancodes. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices */ #ifndef SDL_scancode_h_ @@ -42,7 +47,7 @@ * The values in this enumeration are based on the USB usage page standard: * https://usb.org/sites/default/files/hut1_5.pdf * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_Scancode { @@ -417,8 +422,8 @@ typedef enum SDL_Scancode SDL_SCANCODE_RESERVED = 400, /**< 400-500 reserved for dynamic keycodes */ - SDL_NUM_SCANCODES = 512 /**< not a key, just marks the number of scancodes - for array bounds */ + SDL_SCANCODE_COUNT = 512 /**< not a key, just marks the number of scancodes for array bounds */ + } SDL_Scancode; #endif /* SDL_scancode_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h index 3ae4856..b220f05 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_sensor.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -23,6 +23,12 @@ * # CategorySensor * * SDL sensor management. + * + * These APIs grant access to gyros and accelerometers on various platforms. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_SENSOR flag. This causes SDL to scan the system for sensors, and + * load appropriate drivers. */ #ifndef SDL_sensor_h_ @@ -41,14 +47,10 @@ extern "C" { #endif /** - * SDL_sensor.h + * The opaque structure used to identify an opened SDL sensor. * - * In order to use these functions, SDL_Init() must have been called - * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system - * for sensors, and load appropriate drivers. + * \since This struct is available since SDL 3.2.0. */ - -struct SDL_Sensor; typedef struct SDL_Sensor SDL_Sensor; /** @@ -57,7 +59,7 @@ typedef struct SDL_Sensor SDL_Sensor; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SensorID; @@ -69,7 +71,7 @@ typedef Uint32 SDL_SensorID; * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the * earth, which is a positive Y value. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_STANDARD_GRAVITY 9.80665f @@ -123,7 +125,7 @@ typedef Uint32 SDL_SensorID; * * The gyroscope axis data is not changed when the device is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayOrientation */ @@ -151,7 +153,7 @@ typedef enum SDL_SensorType * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); @@ -163,7 +165,7 @@ extern SDL_DECLSPEC SDL_SensorID * SDLCALL SDL_GetSensors(int *count); * \param instance_id the sensor instance ID. * \returns the sensor name, or NULL if `instance_id` is not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id); @@ -176,7 +178,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID ins * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is * not valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID instance_id); @@ -189,7 +191,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorTypeForID(SDL_SensorID i * \returns the sensor platform dependent type, or -1 if `instance_id` is not * valid. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID instance_id); @@ -200,7 +202,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id); @@ -211,7 +213,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id * \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instance_id); @@ -222,7 +224,7 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_GetSensorFromID(SDL_SensorID instan * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); @@ -233,7 +235,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor * \returns the sensor name or NULL on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); @@ -244,7 +246,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor); * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is * NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor); @@ -254,7 +256,7 @@ extern SDL_DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor) * \param sensor the SDL_Sensor object to inspect. * \returns the sensor platform dependent type, or -1 if `sensor` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor); @@ -265,7 +267,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor) * \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); @@ -277,19 +279,19 @@ extern SDL_DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorID(SDL_Sensor *sensor); * \param sensor the SDL_Sensor object to query. * \param data a pointer filled with the current sensor state. * \param num_values the number of values to write to data. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSensorData(SDL_Sensor *sensor, float *data, int num_values); /** * Close a sensor previously opened with SDL_OpenSensor(). * * \param sensor the SDL_Sensor object to close. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); @@ -302,7 +304,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseSensor(SDL_Sensor *sensor); * This needs to be called from the thread that initialized the sensor * subsystem. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UpdateSensors(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h index 5539f2a..4e15a3c 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_stdinc.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,9 +22,25 @@ /** * # CategoryStdinc * - * This is a general header that includes C language support. It implements a - * subset of the C runtime: these should all behave the same way as their C - * runtime equivalents, but with an SDL_ prefix. + * SDL provides its own implementation of some of the most important C runtime + * functions. + * + * Using these functions allows an app to have access to common C + * functionality without depending on a specific C runtime (or a C runtime at + * all). More importantly, the SDL implementations work identically across + * platforms, so apps can avoid surprises like snprintf() behaving differently + * between Windows and Linux builds, or itoa() only existing on some + * platforms. + * + * For many of the most common functions, like SDL_memcpy, SDL might just call + * through to the usual C runtime behind the scenes, if it makes sense to do + * so (if it's faster and always available/reliable on a given platform), + * reducing library size and offering the most optimized option. + * + * SDL also offers other C-runtime-adjacent functionality in this header that + * either isn't, strictly speaking, part of any C runtime standards, like + * SDL_crc32() and SDL_reinterpret_cast, etc. It also offers a few better + * options, like SDL_strlcpy(), which functions as a safer form of strcpy(). */ #ifndef SDL_stdinc_h_ @@ -32,17 +48,34 @@ #include -#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L -#include -#endif #include -#ifndef __cplusplus -#include -#endif #include #include #include +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + defined(SDL_INCLUDE_INTTYPES_H) +#include +#endif + +#ifndef __cplusplus +#if defined(__has_include) && !defined(SDL_INCLUDE_STDBOOL_H) +#if __has_include() +#define SDL_INCLUDE_STDBOOL_H +#endif +#endif +#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || \ + (defined(_MSC_VER) && (_MSC_VER >= 1910 /* Visual Studio 2017 */)) || \ + defined(SDL_INCLUDE_STDBOOL_H) +#include +#elif !defined(__bool_true_false_are_defined) && !defined(bool) +#define bool unsigned char +#define false 0 +#define true 1 +#define __bool_true_false_are_defined 1 +#endif +#endif /* !__cplusplus */ + #ifndef SDL_DISABLE_ALLOCA # ifndef alloca # ifdef HAVE_ALLOCA_H @@ -74,31 +107,120 @@ void *alloca(size_t); # endif #endif -#ifdef SIZE_MAX + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Don't let SDL use "long long" C types. + * + * SDL will define this if it believes the compiler doesn't understand the + * "long long" syntax for C datatypes. This can happen on older compilers. + * + * If _your_ compiler doesn't support "long long" but SDL doesn't know it, it + * is safe to define this yourself to build against the SDL headers. + * + * If this is defined, it will remove access to some C runtime support + * functions, like SDL_ulltoa and SDL_strtoll that refer to this datatype + * explicitly. The rest of SDL will still be available. + * + * SDL's own source code cannot be built with a compiler that has this + * defined, for various technical reasons. + */ +#define SDL_NOLONGLONG 1 + +#elif defined(_MSC_VER) && (_MSC_VER < 1310) /* long long introduced in Visual Studio.NET 2003 */ +# define SDL_NOLONGLONG 1 +#endif + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * The largest value that a `size_t` can hold for the target platform. + * + * `size_t` is generally the same size as a pointer in modern times, but this + * can get weird on very old and very esoteric machines. For example, on a + * 16-bit Intel 286, you might have a 32-bit "far" pointer (16-bit segment + * plus 16-bit offset), but `size_t` is 16 bits, because it can only deal with + * the offset into an individual segment. + * + * In modern times, it's generally expected to cover an entire linear address + * space. But be careful! + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SIZE_MAX SIZE_MAX + +#elif defined(SIZE_MAX) # define SDL_SIZE_MAX SIZE_MAX #else # define SDL_SIZE_MAX ((size_t) -1) #endif +#ifndef SDL_COMPILE_TIME_ASSERT +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + /** - * Check if the compiler supports a given builtin. - * Supported by virtually all clang versions and recent gcc. Use this - * instead of checking the clang version if possible. + * A compile-time assertion. + * + * This can check constant values _known to the compiler at build time_ for + * correctness, and end the compile with the error if they fail. + * + * Often times these are used to verify basic truths, like the size of a + * datatype is what is expected: + * + * ```c + * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); + * ``` + * + * The `name` parameter must be a valid C symbol, and must be unique across + * all compile-time asserts in the same compilation unit (one run of the + * compiler), or the build might fail with cryptic errors on some targets. + * This is used with a C language trick that works on older compilers that + * don't support better assertion techniques. + * + * If you need an assertion that operates at runtime, on variable data, you + * should try SDL_assert instead. + * + * \param name a unique identifier for this assertion. + * \param x the value to test. Must be a boolean value. + * + * \threadsafety This macro doesn't generate any code to run. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_assert */ -#ifdef __has_builtin -#define SDL_HAS_BUILTIN(x) __has_builtin(x) -#else -#define SDL_HAS_BUILTIN(x) 0 +#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x) +#elif defined(__cplusplus) +/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ +#if (__cplusplus >= 201103L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#endif +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) +#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) +#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) +#endif +#endif /* !SDL_COMPILE_TIME_ASSERT */ + +#ifndef SDL_COMPILE_TIME_ASSERT +/* universal, but may trigger -Wunused-local-typedefs */ +#define SDL_COMPILE_TIME_ASSERT(name, x) \ + typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] #endif /** - * The number of elements in an array. + * The number of elements in a static array. + * + * This will compile but return incorrect results for a pointer to an array; + * it has to be an array the compiler knows the size of. * * This macro looks like it double-evaluates the argument, but it does so * inside of `sizeof`, so there are no side-effects here, as expressions do * not actually run any code in these cases. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) @@ -111,7 +233,9 @@ void *alloca(size_t); * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * ``` * - * \since This macro is available since SDL 3.0.0. + * \param arg the text to turn into a string literal. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -122,7 +246,76 @@ void *alloca(size_t); * -Wold-style-cast of GCC (and -Werror=old-style-cast in GCC 4.2 and above). */ /* @{ */ -#ifdef __cplusplus + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Handle a Reinterpret Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ reinterpret_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_static_cast + * \sa SDL_const_cast + */ +#define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Static Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ static_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_const_cast + */ +#define SDL_static_cast(type, expression) static_cast(expression) /* or `((type)(expression))` in C */ + +/** + * Handle a Const Cast properly whether using C or C++. + * + * If compiled as C++, this macro offers a proper C++ const_cast<>. + * + * If compiled as C, this macro does a normal C-style cast. + * + * This is helpful to avoid compiler warnings in C++. + * + * \param type the type to cast the expression to. + * \param expression the expression to cast to a different type. + * \returns `expression`, cast to `type`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_reinterpret_cast + * \sa SDL_static_cast + */ +#define SDL_const_cast(type, expression) const_cast(expression) /* or `((type)(expression))` in C */ + +#elif defined(__cplusplus) #define SDL_reinterpret_cast(type, expression) reinterpret_cast(expression) #define SDL_static_cast(type, expression) static_cast(expression) #define SDL_const_cast(type, expression) const_cast(expression) @@ -131,9 +324,23 @@ void *alloca(size_t); #define SDL_static_cast(type, expression) ((type)(expression)) #define SDL_const_cast(type, expression) ((type)(expression)) #endif + /* @} *//* Cast operators */ -/* Define a four character code as a Uint32 */ +/** + * Define a four character code as a Uint32. + * + * \param A the first ASCII character. + * \param B the second ASCII character. + * \param C the third ASCII character. + * \param D the fourth ASCII character. + * \returns the four characters converted into a Uint32, one character + * per-byte. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_FOURCC(A, B, C, D) \ ((SDL_static_cast(Uint32, SDL_static_cast(Uint8, (A))) << 0) | \ (SDL_static_cast(Uint32, SDL_static_cast(Uint8, (B))) << 8) | \ @@ -149,7 +356,7 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_SINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -162,63 +369,49 @@ void *alloca(size_t); * 0xFFFFFFFF is overflowing a 32-bit value. Use `SDL_UINT64_C(0xFFFFFFFF1)` * instead of `0xFFFFFFFF1` by itself. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ #define SDL_UINT64_C(c) c ## ULL /* or whatever the current compiler uses. */ -#elif defined(INT64_C) +#else /* !SDL_WIKI_DOCUMENTATION_SECTION */ + +#ifndef SDL_SINT64_C +#if defined(INT64_C) #define SDL_SINT64_C(c) INT64_C(c) -#define SDL_UINT64_C(c) UINT64_C(c) #elif defined(_MSC_VER) #define SDL_SINT64_C(c) c ## i64 -#define SDL_UINT64_C(c) c ## ui64 #elif defined(__LP64__) || defined(_LP64) #define SDL_SINT64_C(c) c ## L -#define SDL_UINT64_C(c) c ## UL #else #define SDL_SINT64_C(c) c ## LL +#endif +#endif /* !SDL_SINT64_C */ + +#ifndef SDL_UINT64_C +#if defined(UINT64_C) +#define SDL_UINT64_C(c) UINT64_C(c) +#elif defined(_MSC_VER) +#define SDL_UINT64_C(c) c ## ui64 +#elif defined(__LP64__) || defined(_LP64) +#define SDL_UINT64_C(c) c ## UL +#else #define SDL_UINT64_C(c) c ## ULL #endif +#endif /* !SDL_UINT64_C */ + +#endif /* !SDL_WIKI_DOCUMENTATION_SECTION */ /** * \name Basic data types */ /* @{ */ -/** - * A boolean false. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_FALSE false - -/** - * A boolean true. - * - * \since This macro is available since SDL 3.0.0. - * - * \sa SDL_bool - */ -#define SDL_TRUE true - -/** - * A boolean type: true or false. - * - * \since This datatype is available since SDL 3.0.0. - * - * \sa SDL_TRUE - * \sa SDL_FALSE - */ -typedef bool SDL_bool; - /** * A signed 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int8_t Sint8; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ @@ -227,7 +420,7 @@ typedef int8_t Sint8; /** * An unsigned 8-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint8_t Uint8; #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ @@ -236,7 +429,7 @@ typedef uint8_t Uint8; /** * A signed 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int16_t Sint16; #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ @@ -245,7 +438,7 @@ typedef int16_t Sint16; /** * An unsigned 16-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint16_t Uint16; #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ @@ -254,7 +447,7 @@ typedef uint16_t Uint16; /** * A signed 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef int32_t Sint32; #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ @@ -263,7 +456,7 @@ typedef int32_t Sint32; /** * An unsigned 32-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ typedef uint32_t Uint32; #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ @@ -272,7 +465,7 @@ typedef uint32_t Uint32; /** * A signed 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_SINT64_C */ @@ -283,7 +476,7 @@ typedef int64_t Sint64; /** * An unsigned 64-bit integer type. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_UINT64_C */ @@ -299,7 +492,7 @@ typedef uint64_t Uint64; * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with * SDL_TimeToWindows() and SDL_TimeFromWindows(). * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * * \sa SDL_MAX_SINT64 * \sa SDL_MIN_SINT64 @@ -325,40 +518,217 @@ typedef Sint64 SDL_Time; * Equals by default to platform-defined `FLT_EPSILON`, or * `1.1920928955078125e-07F` if that's not available. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_FLT_EPSILON 1.1920928955078125e-07F /* 0x0.000002p0 */ #endif /* @} *//* Floating-point constants */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A printf-formatting string for an Sint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs64 "lld" + +/** + * A printf-formatting string for a Uint64 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu64 "llu" + +/** + * A printf-formatting string for a Uint64 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx64 "llx" + +/** + * A printf-formatting string for a Uint64 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX64 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX64 "llX" + +/** + * A printf-formatting string for an Sint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIs32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIs32 "d" + +/** + * A printf-formatting string for a Uint32 value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIu32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIu32 "u" + +/** + * A printf-formatting string for a Uint32 value as lower-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIx32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIx32 "x" + +/** + * A printf-formatting string for a Uint32 value as upper-case hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRIX32 " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRIX32 "X" + +/** + * A printf-formatting string prefix for a `long long` value. + * + * This is just the prefix! You probably actually want SDL_PRILLd, SDL_PRILLu, + * SDL_PRILLx, or SDL_PRILLX instead. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILL_PREFIX "d bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILL_PREFIX "ll" + +/** + * A printf-formatting string for a `long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLd " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLd SDL_PRILL_PREFIX "d" + +/** + * A printf-formatting string for a `unsigned long long` value. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLu " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLu SDL_PRILL_PREFIX "u" + +/** + * A printf-formatting string for an `unsigned long long` value as lower-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLx " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLx SDL_PRILL_PREFIX "x" + +/** + * A printf-formatting string for an `unsigned long long` value as upper-case + * hexadecimal. + * + * Use it like this: + * + * ```c + * SDL_Log("There are %" SDL_PRILLX " bottles of beer on the wall.", bottles); + * ``` + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* SDL_WIKI_DOCUMENTATION_SECTION */ + /* Make sure we have macros for printing width-based integers. - * should define these but this is not true all platforms. + * should define these but this is not true all platforms. * (for example win32) */ #ifndef SDL_PRIs64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIs64 "I64d" -#elif defined(PRIs64) -#define SDL_PRIs64 PRIs64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(PRId64) +#define SDL_PRIs64 PRId64 +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIs64 "ld" #else #define SDL_PRIs64 "lld" #endif #endif #ifndef SDL_PRIu64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIu64 "I64u" #elif defined(PRIu64) #define SDL_PRIu64 PRIu64 -#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) +#elif defined(__LP64__) && !defined(SDL_PLATFORM_APPLE) && !defined(__EMSCRIPTEN__) #define SDL_PRIu64 "lu" #else #define SDL_PRIu64 "llu" #endif #endif #ifndef SDL_PRIx64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIx64 "I64x" #elif defined(PRIx64) #define SDL_PRIx64 PRIx64 @@ -369,7 +739,7 @@ typedef Sint64 SDL_Time; #endif #endif #ifndef SDL_PRIX64 -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) #define SDL_PRIX64 "I64X" #elif defined(PRIX64) #define SDL_PRIX64 PRIX64 @@ -407,9 +777,318 @@ typedef Sint64 SDL_Time; #define SDL_PRIX32 "X" #endif #endif +/* Specifically for the `long long` -- SDL-specific. */ +#ifdef SDL_PLATFORM_WINDOWS +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 for windows - make sure `long long` is 64 bits. */ +#endif +#define SDL_PRILL_PREFIX "I64" +#else +#define SDL_PRILL_PREFIX "ll" +#endif +#ifndef SDL_PRILLd +#define SDL_PRILLd SDL_PRILL_PREFIX "d" +#endif +#ifndef SDL_PRILLu +#define SDL_PRILLu SDL_PRILL_PREFIX "u" +#endif +#ifndef SDL_PRILLx +#define SDL_PRILLx SDL_PRILL_PREFIX "x" +#endif +#ifndef SDL_PRILLX +#define SDL_PRILLX SDL_PRILL_PREFIX "X" +#endif /* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Macro that annotates function params with input buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + * ``` + * + * This notes that `src` should be `len` bytes in size and is only read by the + * function. The compiler or other analysis tools can warn when this doesn't + * appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) + +/** + * Macro that annotates function params with input/output string buffer size. + * + * If we were to annotate `strlcat`: + * + * ```c + * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + * ``` + * + * This notes that `dst` is a null-terminated C string, should be `maxlen` + * bytes in size, and is both read from and written to by the function. The + * compiler or other analysis tools can warn when this doesn't appear to be + * the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) + +/** + * Macro that annotates function params with output string buffer size. + * + * If we were to annotate `snprintf`: + * + * ```c + * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...); + * ``` + * + * This notes that `text` is a null-terminated C string, should be `maxlen` + * bytes in size, and is only written to by the function. The compiler or + * other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `wcsncpy`: + * + * ```c + * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` wchar_t in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for + * bytes. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_CAP(x) _Out_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) + +/** + * Macro that annotates function params with output buffer string size. + * + * If we were to annotate `strcpy`: + * + * ```c + * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and a zero-terminated string is written to it by the function. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +/** + * Macro that annotates function params as printf-style format strings. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a printf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ + +/** + * Macro that annotates function params as scanf-style format strings. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a scanf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ + +/** + * Macro that annotates a vararg function that operates like printf. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like printf. + * + * If we were to annotate `vfprintf`: + * + * ```c + * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a printf-style format + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like scanf. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by `...`. The compiler or other analysis tools can warn when this + * doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like scanf. + * + * If we were to annotate `vfscanf`: + * + * ```c + * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, + * followed by a va_list. The compiler or other analysis tools can warn when + * this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like wprintf. + * + * If we were to annotate `fwprintf`: + * + * ```c + * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by `...`. The compiler or other analysis tools can warn + * when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ + +/** + * Macro that annotates a va_list function that operates like wprintf. + * + * If we were to annotate `vfwprintf`: + * + * ```c + * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide + * string, followed by a va_list. The compiler or other analysis tools can + * warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which + * between them will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + +#elif defined(SDL_DISABLE_ANALYZE_MACROS) #define SDL_IN_BYTECAP(x) #define SDL_INOUT_Z_CAP(x) #define SDL_OUT_Z_CAP(x) @@ -423,7 +1102,7 @@ typedef Sint64 SDL_Time; #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -447,53 +1126,45 @@ typedef Sint64 SDL_Time; #define SDL_PRINTF_FORMAT_STRING #define SDL_SCANF_FORMAT_STRING #endif -#ifdef __GNUC__ +#if defined(__GNUC__) || defined(__clang__) #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) #define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) -#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ -#ifndef SDL_COMPILE_TIME_ASSERT -#if defined(__cplusplus) -/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */ -#if (__cplusplus >= 201103L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#endif -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 202311L) -#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x) -#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) -#define SDL_COMPILE_TIME_ASSERT(name, x) _Static_assert(x, #x) -#endif -#endif /* !SDL_COMPILE_TIME_ASSERT */ - -#ifndef SDL_COMPILE_TIME_ASSERT -/* universal, but may trigger -Wunused-local-typedefs */ -#define SDL_COMPILE_TIME_ASSERT(name, x) \ - typedef int SDL_compile_time_assert_ ## name[(x) * 2 - 1] -#endif - /** \cond */ #ifndef DOXYGEN_SHOULD_IGNORE_THIS -SDL_COMPILE_TIME_ASSERT(bool, sizeof(SDL_bool) == 1); -SDL_COMPILE_TIME_ASSERT(uint8, sizeof(Uint8) == 1); -SDL_COMPILE_TIME_ASSERT(sint8, sizeof(Sint8) == 1); -SDL_COMPILE_TIME_ASSERT(uint16, sizeof(Uint16) == 2); -SDL_COMPILE_TIME_ASSERT(sint16, sizeof(Sint16) == 2); -SDL_COMPILE_TIME_ASSERT(uint32, sizeof(Uint32) == 4); -SDL_COMPILE_TIME_ASSERT(sint32, sizeof(Sint32) == 4); -SDL_COMPILE_TIME_ASSERT(uint64, sizeof(Uint64) == 8); -SDL_COMPILE_TIME_ASSERT(sint64, sizeof(Sint64) == 8); +SDL_COMPILE_TIME_ASSERT(bool_size, sizeof(bool) == 1); +SDL_COMPILE_TIME_ASSERT(uint8_size, sizeof(Uint8) == 1); +SDL_COMPILE_TIME_ASSERT(sint8_size, sizeof(Sint8) == 1); +SDL_COMPILE_TIME_ASSERT(uint16_size, sizeof(Uint16) == 2); +SDL_COMPILE_TIME_ASSERT(sint16_size, sizeof(Sint16) == 2); +SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4); +SDL_COMPILE_TIME_ASSERT(sint32_size, sizeof(Sint32) == 4); +SDL_COMPILE_TIME_ASSERT(uint64_size, sizeof(Uint64) == 8); +SDL_COMPILE_TIME_ASSERT(sint64_size, sizeof(Sint64) == 8); +#ifndef SDL_NOLONGLONG +SDL_COMPILE_TIME_ASSERT(uint64_longlong, sizeof(Uint64) <= sizeof(unsigned long long)); +SDL_COMPILE_TIME_ASSERT(size_t_longlong, sizeof(size_t) <= sizeof(unsigned long long)); +#endif +typedef struct SDL_alignment_test +{ + Uint8 a; + void *b; +} SDL_alignment_test; +SDL_COMPILE_TIME_ASSERT(struct_alignment, sizeof(SDL_alignment_test) == (2 * sizeof(void *))); +SDL_COMPILE_TIME_ASSERT(two_s_complement, (int)~(int)0 == (int)(-1)); #endif /* DOXYGEN_SHOULD_IGNORE_THIS */ /** \endcond */ @@ -523,7 +1194,96 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int)); extern "C" { #endif -#ifndef SDL_DISABLE_ALLOCA +/** + * A macro to initialize an SDL interface. + * + * This macro will initialize an SDL interface structure and should be called + * before you fill out the fields with your implementation. + * + * You can use it like this: + * + * ```c + * SDL_IOStreamInterface iface; + * + * SDL_INIT_INTERFACE(&iface); + * + * // Fill in the interface function pointers with your implementation + * iface.seek = ... + * + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * If you are using designated initializers, you can use the size of the + * interface as the version, e.g. + * + * ```c + * SDL_IOStreamInterface iface = { + * .version = sizeof(iface), + * .seek = ... + * }; + * stream = SDL_OpenIO(&iface, NULL); + * ``` + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_IOStreamInterface + * \sa SDL_StorageInterface + * \sa SDL_VirtualJoystickDesc + */ +#define SDL_INIT_INTERFACE(iface) \ + do { \ + SDL_zerop(iface); \ + (iface)->version = sizeof(*(iface)); \ + } while (0) + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Allocate memory on the stack (maybe). + * + * If SDL knows how to access alloca() on the current platform, it will use it + * to stack-allocate memory here. If it doesn't, it will use SDL_malloc() to + * heap-allocate memory. + * + * Since this might not be stack memory at all, it's important that you check + * the returned pointer for NULL, and that you call SDL_stack_free on the + * memory when done with it. Since this might be stack memory, it's important + * that you don't allocate large amounts of it, or allocate in a loop without + * returning from the function, so the stack doesn't overflow. + * + * \param type the datatype of the memory to allocate. + * \param count the number of `type` objects to allocate. + * \returns newly-allocated memory, or NULL on failure. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_free + */ +#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) + +/** + * Free memory previously allocated with SDL_stack_alloc. + * + * If SDL used alloca() to allocate this memory, this macro does nothing and + * the allocated memory will be automatically released when the function that + * called SDL_stack_alloc() returns. If SDL used SDL_malloc(), it will + * SDL_free the memory immediately. + * + * \param data the pointer, from SDL_stack_alloc(), to free. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_stack_alloc + */ +#define SDL_stack_free(data) +#elif !defined(SDL_DISABLE_ALLOCA) #define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count)) #define SDL_stack_free(data) #else @@ -531,14 +1291,184 @@ extern "C" { #define SDL_stack_free(data) SDL_free(data) #endif +/** + * Allocate uninitialized memory. + * + * The allocated memory returned by this function must be freed with + * SDL_free(). + * + * If `size` is 0, it will be set to 1. + * + * If you want to allocate memory aligned to a specific alignment, consider + * using SDL_aligned_alloc(). + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_calloc + * \sa SDL_realloc + * \sa SDL_aligned_alloc + */ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size); + +/** + * Allocate a zero-initialized array. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If either of `nmemb` or `size` is 0, they will both be set to 1. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(size_t nmemb, size_t size); + +/** + * Change the size of allocated memory. + * + * The memory returned by this function must be freed with SDL_free(). + * + * If `size` is 0, it will be set to 1. Note that this is unlike some other C + * runtime `realloc` implementations, which may treat `realloc(mem, 0)` the + * same way as `free(mem)`. + * + * If `mem` is NULL, the behavior of this function is equivalent to + * SDL_malloc(). Otherwise, the function can have one of three possible + * outcomes: + * + * - If it returns the same pointer as `mem`, it means that `mem` was resized + * in place without freeing. + * - If it returns a different non-NULL pointer, it means that `mem` was freed + * and cannot be dereferenced anymore. + * - If it returns NULL (indicating failure), then `mem` will remain valid and + * must still be freed with SDL_free(). + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_malloc + * \sa SDL_calloc + */ extern SDL_DECLSPEC SDL_ALLOC_SIZE(2) void * SDLCALL SDL_realloc(void *mem, size_t size); + +/** + * Free allocated memory. + * + * The pointer is no longer valid after this call and cannot be dereferenced + * anymore. + * + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer to allocated memory, or NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_calloc + * \sa SDL_realloc + */ extern SDL_DECLSPEC void SDLCALL SDL_free(void *mem); +/** + * A callback used to implement SDL_malloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param size the size to allocate. + * \returns a pointer to the allocated memory, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_malloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_malloc_func)(size_t size); + +/** + * A callback used to implement SDL_calloc(). + * + * SDL will always ensure that the passed `nmemb` and `size` are both greater + * than 0. + * + * \param nmemb the number of elements in the array. + * \param size the size of each element of the array. + * \returns a pointer to the allocated array, or NULL if allocation failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_calloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_calloc_func)(size_t nmemb, size_t size); + +/** + * A callback used to implement SDL_realloc(). + * + * SDL will always ensure that the passed `size` is greater than 0. + * + * \param mem a pointer to allocated memory to reallocate, or NULL. + * \param size the new size of the memory. + * \returns a pointer to the newly allocated memory, or NULL if allocation + * failed. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_realloc + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); + +/** + * A callback used to implement SDL_free(). + * + * SDL will always ensure that the passed `mem` is a non-NULL pointer. + * + * \param mem a pointer to allocated memory. + * + * \threadsafety It should be safe to call this callback from any thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_free + * \sa SDL_GetOriginalMemoryFunctions + * \sa SDL_GetMemoryFunctions + * \sa SDL_SetMemoryFunctions + */ typedef void (SDLCALL *SDL_free_func)(void *mem); /** @@ -556,7 +1486,7 @@ typedef void (SDLCALL *SDL_free_func)(void *mem); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *malloc_func, SDL_calloc_func *calloc_func, @@ -575,7 +1505,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func * unlikely event of a background thread calling * SDL_SetMemoryFunctions simultaneously. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions @@ -599,42 +1529,42 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_ * \param calloc_func custom calloc function. * \param realloc_func custom realloc function. * \param free_func custom free function. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread, but one * should not replace the memory functions once any allocations * are made! * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetMemoryFunctions * \sa SDL_GetOriginalMemoryFunctions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, +extern SDL_DECLSPEC bool SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_calloc_func calloc_func, SDL_realloc_func realloc_func, SDL_free_func free_func); /** - * Allocate memory aligned to a specific value. - * - * If `alignment` is less than the size of `void *`, then it will be increased - * to match that. - * - * The returned memory address will be a multiple of the alignment value, and - * the amount of memory allocated will be a multiple of the alignment value. + * Allocate memory aligned to a specific alignment. * * The memory returned by this function must be freed with SDL_aligned_free(), - * and _not_ SDL_free. + * _not_ SDL_free(). * - * \param alignment the alignment requested. + * If `alignment` is less than the size of `void *`, it will be increased to + * match that. + * + * The returned memory address will be a multiple of the alignment value, and + * the size of the memory allocated will be a multiple of the alignment value. + * + * \param alignment the alignment of the memory. * \param size the size to allocate. - * \returns a pointer to the aligned memory. + * \returns a pointer to the aligned memory, or NULL if allocation failed. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_free */ @@ -646,11 +1576,13 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_aligned_alloc(size_t alignment * The pointer is no longer valid after this call and cannot be dereferenced * anymore. * - * \param mem a pointer previously returned by SDL_aligned_alloc. + * If `mem` is NULL, this function does nothing. + * + * \param mem a pointer previously returned by SDL_aligned_alloc(), or NULL. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_aligned_alloc */ @@ -659,31 +1591,552 @@ extern SDL_DECLSPEC void SDLCALL SDL_aligned_free(void *mem); /** * Get the number of outstanding (unfreed) allocations. * - * \returns the number of allocations. + * \returns the number of allocations or -1 if allocation counting is + * disabled. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAllocations(void); -extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); -extern SDL_DECLSPEC int SDLCALL SDL_setenv(const char *name, const char *value, int overwrite); -extern SDL_DECLSPEC int SDLCALL SDL_unsetenv(const char *name); +/** + * A thread-safe set of environment variables + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +typedef struct SDL_Environment SDL_Environment; +/** + * Get the process environment. + * + * This is initialized at application start and is not affected by setenv() + * and unsetenv() calls after that point. Use SDL_SetEnvironmentVariable() and + * SDL_UnsetEnvironmentVariable() if you want to modify this environment, or + * SDL_setenv_unsafe() or SDL_unsetenv_unsafe() if you want changes to persist + * in the C runtime environment after SDL_Quit(). + * + * \returns a pointer to the environment for the process or NULL on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_GetEnvironment(void); + +/** + * Create a set of environment variables + * + * \param populated true to initialize it from the C runtime environment, + * false to create an empty environment. + * \returns a pointer to the new environment or NULL on failure; call + * SDL_GetError() for more information. + * + * \threadsafety If `populated` is false, it is safe to call this function + * from any thread, otherwise it is safe if no other threads are + * calling setenv() or unsetenv() + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + * \sa SDL_DestroyEnvironment + */ +extern SDL_DECLSPEC SDL_Environment * SDLCALL SDL_CreateEnvironment(bool populated); + +/** + * Get the value of a variable in the environment. + * + * \param env the environment to query. + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_GetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Get all variables in the environment. + * + * \param env the environment to query. + * \returns a NULL terminated array of pointers to environment variables in + * the form "variable=value" or NULL on failure; call SDL_GetError() + * for more information. This is a single allocation that should be + * freed with SDL_free() when it is no longer needed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC char ** SDLCALL SDL_GetEnvironmentVariables(SDL_Environment *env); + +/** + * Set the value of a variable in the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite true to overwrite the variable if it exists, false to + * return success without setting the variable if it already + * exists. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetEnvironmentVariable(SDL_Environment *env, const char *name, const char *value, bool overwrite); + +/** + * Clear a variable from the environment. + * + * \param env the environment to modify. + * \param name the name of the variable to unset. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetEnvironment + * \sa SDL_CreateEnvironment + * \sa SDL_GetEnvironmentVariable + * \sa SDL_GetEnvironmentVariables + * \sa SDL_SetEnvironmentVariable + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC bool SDLCALL SDL_UnsetEnvironmentVariable(SDL_Environment *env, const char *name); + +/** + * Destroy a set of environment variables. + * + * \param env the environment to destroy. + * + * \threadsafety It is safe to call this function from any thread, as long as + * the environment is no longer in use. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateEnvironment + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyEnvironment(SDL_Environment *env); + +/** + * Get the value of a variable in the environment. + * + * This function uses SDL's cached copy of the environment and is thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv(const char *name); + +/** + * Get the value of a variable in the environment. + * + * This function bypasses SDL's cached copy of the environment and is not + * thread-safe. + * + * \param name the name of the variable to get. + * \returns a pointer to the value of the variable or NULL if it can't be + * found. + * + * \threadsafety This function is not thread safe, consider using SDL_getenv() + * instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_getenv + */ +extern SDL_DECLSPEC const char * SDLCALL SDL_getenv_unsafe(const char *name); + +/** + * Set the value of a variable in the environment. + * + * \param name the name of the variable to set. + * \param value the value of the variable to set. + * \param overwrite 1 to overwrite the variable if it exists, 0 to return + * success without setting the variable if it already exists. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_SetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_setenv_unsafe(const char *name, const char *value, int overwrite); + +/** + * Clear a variable from the environment. + * + * \param name the name of the variable to unset. + * \returns 0 on success, -1 on error. + * + * \threadsafety This function is not thread safe, consider using + * SDL_UnsetEnvironmentVariable() instead. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UnsetEnvironmentVariable + */ +extern SDL_DECLSPEC int SDLCALL SDL_unsetenv_unsafe(const char *name); + +/** + * A callback used with SDL sorting and binary search functions. + * + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort + */ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); + +/** + * Sort an array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort(values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); + +/** + * Perform a binary search on a previously sorted array. + * + * For example: + * + * ```c + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *a, const void *b) + * { + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->n < B->n) { + * return -1; + * } else if (B->n < A->n) { + * return 1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch(&key, values, SDL_arraysize(values), sizeof(values[0]), compare); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback compare); +/** + * A callback used with SDL sorting and binary search functions. + * + * \param userdata the `userdata` pointer passed to the sort function. + * \param a a pointer to the first element being compared. + * \param b a pointer to the second element being compared. + * \returns -1 if `a` should be sorted before `b`, 1 if `b` should be sorted + * before `a`, 0 if they are equal. If two elements are equal, their + * order in the sorted array is undefined. + * + * \since This callback is available since SDL 3.2.0. + * + * \sa SDL_qsort_r + * \sa SDL_bsearch_r + */ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, const void *b); + +/** + * Sort an array, passing a userdata pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 3, "third" }, { 1, "first" }, { 2, "second" } + * }; + * + * SDL_qsort_r(values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch_r + * \sa SDL_qsort + */ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); + +/** + * Perform a binary search on a previously sorted array, passing a userdata + * pointer to the compare function. + * + * For example: + * + * ```c + * typedef enum { + * sort_increasing, + * sort_decreasing, + * } sort_method; + * + * typedef struct { + * int key; + * const char *string; + * } data; + * + * int SDLCALL compare(const void *userdata, const void *a, const void *b) + * { + * sort_method method = (sort_method)(uintptr_t)userdata; + * const data *A = (const data *)a; + * const data *B = (const data *)b; + * + * if (A->key < B->key) { + * return (method == sort_increasing) ? -1 : 1; + * } else if (B->key < A->key) { + * return (method == sort_increasing) ? 1 : -1; + * } else { + * return 0; + * } + * } + * + * data values[] = { + * { 1, "first" }, { 2, "second" }, { 3, "third" } + * }; + * data key = { 2, NULL }; + * + * data *result = SDL_bsearch_r(&key, values, SDL_arraysize(values), sizeof(values[0]), compare, (const void *)(uintptr_t)sort_increasing); + * ``` + * + * \param key a pointer to a key equal to the element being searched for. + * \param base a pointer to the start of the array. + * \param nmemb the number of elements in the array. + * \param size the size of the elements in the array. + * \param compare a function used to compare elements in the array. + * \param userdata a pointer to pass to the compare function. + * \returns a pointer to the matching element in the array, or NULL if not + * found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_bsearch + * \sa SDL_qsort_r + */ extern SDL_DECLSPEC void * SDLCALL SDL_bsearch_r(const void *key, const void *base, size_t nmemb, size_t size, SDL_CompareCallback_r compare, void *userdata); +/** + * Compute the absolute value of `x`. + * + * \param x an integer value. + * \returns the absolute value of x. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); -/* NOTE: these double-evaluate their arguments, so you should never have side effects in the parameters */ +/** + * Return the lesser of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_min(x, y) (((x) < (y)) ? (x) : (y)) + +/** + * Return the greater of two values. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `>` operator. However, it double-evaluates both its parameters, so do not + * use expressions with side-effects here. + * + * \param x the first value to compare. + * \param y the second value to compare. + * \returns the lesser of `x` and `y`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_max(x, y) (((x) > (y)) ? (x) : (y)) + +/** + * Return a value clamped to a range. + * + * If `x` is outside the range a values between `a` and `b`, the returned + * value will be `a` or `b` as appropriate. Otherwise, `x` is returned. + * + * This macro will produce incorrect results if `b` is less than `a`. + * + * This is a helper macro that might be more clear than writing out the + * comparisons directly, and works with any type that can be compared with the + * `<` and `>` operators. However, it double-evaluates all its parameters, so + * do not use expressions with side-effects here. + * + * \param x the value to compare. + * \param a the low end value. + * \param b the high end value. + * \returns x, clamped between a and b. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_clamp(x, a, b) (((x) < (a)) ? (a) : (((x) > (b)) ? (b) : (x))) /** @@ -697,7 +2150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_abs(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); @@ -712,7 +2165,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalpha(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); @@ -727,7 +2180,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isalnum(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); @@ -742,7 +2195,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isblank(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); @@ -757,7 +2210,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_iscntrl(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); @@ -772,7 +2225,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); @@ -787,7 +2240,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isxdigit(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isgraph * \sa SDL_isalnum @@ -812,7 +2265,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ispunct(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); @@ -827,7 +2280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isspace(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); @@ -842,7 +2295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); @@ -861,7 +2314,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_islower(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); @@ -880,7 +2333,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isprint(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isprint */ @@ -900,7 +2353,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); @@ -918,13 +2371,96 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_tolower(int x); +/** + * Calculate a CRC-16 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-16 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-16 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint16 SDLCALL SDL_crc16(Uint16 crc, const void *data, size_t len); + +/** + * Calculate a CRC-32 value. + * + * https://en.wikipedia.org/wiki/Cyclic_redundancy_check + * + * This function can be called multiple times, to stream data to be + * checksummed in blocks. Each call must provide the previous CRC-32 return + * value to be updated with the next block. The first call to this function + * for a set of blocks should pass in a zero CRC value. + * + * \param crc the current checksum for this data set, or 0 for a new data set. + * \param data a new block of data to add to the checksum. + * \param len the size, in bytes, of the new block of data. + * \returns a CRC-32 checksum value of all blocks in the data set. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_crc32(Uint32 crc, const void *data, size_t len); +/** + * Calculate a 32-bit MurmurHash3 value for a block of data. + * + * https://en.wikipedia.org/wiki/MurmurHash + * + * A seed may be specified, which changes the final results consistently, but + * this does not work like SDL_crc16 and SDL_crc32: you can't feed a previous + * result from this function back into itself as the next seed value to + * calculate a hash in chunks; it won't produce the same hash as it would if + * the same data was provided in a single call. + * + * If you aren't sure what to provide for a seed, zero is fine. Murmur3 is not + * cryptographically secure, so it shouldn't be used for hashing top-secret + * data. + * + * \param data the data to be hashed. + * \param len the size of data, in bytes. + * \param seed a value that alters the final hash value. + * \returns a Murmur3 32-bit hash value. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_murmur3_32(const void *data, size_t len, Uint32 seed); + +/** + * Copy non-overlapping memory. + * + * The memory regions must not overlap. If they do, use SDL_memmove() instead. + * + * \param dst The destination memory region. Must not be NULL, and must not + * overlap with `src`. + * \param src The source memory region. Must not be NULL, and must not overlap + * with `dst`. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memmove + */ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memcpy */ @@ -935,10 +2471,52 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memcpy(SDL_OUT_BYTECAP(len) void *dst, SD #define SDL_memcpy memcpy #endif + +/** + * A macro to copy memory between objects, with basic type checking. + * + * SDL_memcpy and SDL_memmove do not care where you copy memory to and from, + * which can lead to bugs. This macro aims to avoid most of those bugs by + * making sure that the source and destination are both pointers to objects + * that are the same size. It does not check that the objects are the same + * _type_, just that the copy will not overflow either object. + * + * The size check happens at compile time, and the compiler will throw an + * error if the objects are different sizes. + * + * Generally this is intended to copy a single object, not an array. + * + * This macro looks like it double-evaluates its parameters, but the extras + * them are in `sizeof` sections, which generate no code nor side-effects. + * + * \param dst a pointer to the destination object. Must not be NULL. + * \param src a pointer to the source object. Must not be NULL. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ #define SDL_copyp(dst, src) \ { SDL_COMPILE_TIME_ASSERT(SDL_copyp, sizeof (*(dst)) == sizeof (*(src))); } \ SDL_memcpy((dst), (src), sizeof(*(src))) +/** + * Copy memory ranges that might overlap. + * + * It is okay for the memory regions to overlap. If you are confident that the + * regions never overlap, using SDL_memcpy() may improve performance. + * + * \param dst The destination memory region. Must not be NULL. + * \param src The source memory region. Must not be NULL. + * \param len The length in bytes of both `dst` and `src`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_memcpy + */ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); /* Take advantage of compiler optimizations for memmove */ @@ -949,7 +2527,44 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memmove(SDL_OUT_BYTECAP(len) void *dst, S #define SDL_memmove memmove #endif +/** + * Initialize all bytes of buffer of memory to a specific value. + * + * This function will set `len` bytes, pointed to by `dst`, to the value + * specified in `c`. + * + * Despite `c` being an `int` instead of a `char`, this only operates on + * bytes; `c` must be a value between 0 and 255, inclusive. + * + * \param dst the destination memory region. Must not be NULL. + * \param c the byte value to set. + * \param len the length, in bytes, to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset(SDL_OUT_BYTECAP(len) void *dst, int c, size_t len); + +/** + * Initialize all 32-bit words of buffer of memory to a specific value. + * + * This function will set a buffer of `dwords` Uint32 values, pointed to by + * `dst`, to the value specified in `val`. + * + * Unlike SDL_memset, this sets 32-bit values, not bytes, so it's not limited + * to a range of 0-255. + * + * \param dst the destination memory region. Must not be NULL. + * \param val the Uint32 value to set. + * \param dwords the number of Uint32 values to set in `dst`. + * \returns `dst`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwords); /* Take advantage of compiler optimizations for memset */ @@ -960,18 +2575,255 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo #define SDL_memset memset #endif +/** + * Clear an object's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an object, not a pointer to an object, nor an array. + * + * \param x the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zerop + * \sa SDL_zeroa + */ #define SDL_zero(x) SDL_memset(&(x), 0, sizeof((x))) + +/** + * Clear an object's memory to zero, using a pointer. + * + * This is wrapper over SDL_memset that handles calculating the object size, + * so there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires a pointer to an object, not an object itself, nor an array. + * + * \param x a pointer to the object to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zerop(x) SDL_memset((x), 0, sizeof(*(x))) + +/** + * Clear an array's memory to zero. + * + * This is wrapper over SDL_memset that handles calculating the array size, so + * there's no chance of copy/paste errors, and the code is cleaner. + * + * This requires an array, not an object, nor a pointer to an object. + * + * \param x an array to clear. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_zero + * \sa SDL_zeroa + */ #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) + +/** + * Compare two buffers of memory. + * + * \param s1 the first buffer to compare. NULL is not permitted! + * \param s2 the second buffer to compare. NULL is not permitted! + * \param len the number of bytes to compare between the buffers. + * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is + * "greater than" s2, and zero if the buffers match exactly for `len` + * bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); +/** + * This works exactly like wcslen() but doesn't require access to a C runtime. + * + * Counts the number of wchar_t values in `wstr`, excluding the null + * terminator. + * + * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \returns the length (in wchar_t values, excluding the null terminator) of + * `wstr`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcsnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); + +/** + * This works exactly like wcsnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the + * null terminator. + * + * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * Also, `maxlen` is a count of wide characters, not bytes! + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \param maxlen The maximum amount of wide characters to count. + * \returns the length (in wide characters, excluding the null terminator) of + * `wstr` but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); + +/** + * Copy a wide string. + * + * This function copies `maxlen` - 1 wide characters from `src` to `dst`, then + * appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` is 0, no wide characters are copied and no null terminator is + * written. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated wide string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcat + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Concatenate wide strings. + * + * This function appends up to `maxlen` - SDL_wcslen(dst) - 1 wide characters + * from `src` to the end of the wide string in `dst`, then appends a null + * terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_wcslen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated wide string. Must not be NULL and must not + * overlap with `src`. + * \param src The second null-terminated wide string. Must not be NULL, and + * must not overlap with `dst`. + * \param maxlen The length (in wide characters) of the destination buffer. + * \returns the length (in wide characters, excluding the null terminator) of + * the string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_wcslcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); + +/** + * Allocate a copy of a wide string. + * + * This allocates enough space for a null-terminated copy of `wstr`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param wstr the string to copy. + * \returns a pointer to the newly-allocated wide string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); + +/** + * Search a wide string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); + +/** + * Search a wide string, up to n wide chars, for the first instance of a + * specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * value to end the string, or `maxlen` wide character have been examined. It + * is possible to use this function on a wide string without a null + * terminator. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \param maxlen the maximum number of wide characters to search in + * `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -989,7 +2841,7 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2); @@ -1020,7 +2872,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *s * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); @@ -1050,7 +2902,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t * * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); @@ -1092,19 +2944,228 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_ * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); +/** + * Parse a `long` from a wide string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated wide string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid wide character + * (i.e. the next character after the parsed number) will be + * written to this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strtol + */ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); +/** + * This works exactly like strlen() but doesn't require access to a C runtime. + * + * Counts the bytes in `str`, excluding the null terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the length (in bytes, excluding the null terminator) of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); + +/** + * This works exactly like strnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` bytes in `str`, excluding the null + * terminator. + * + * If you need the length of a UTF-8 string, consider using SDL_utf8strnlen(). + * + * \param str The null-terminated string to read. Must not be NULL. + * \param maxlen The maximum amount of bytes to count. + * \returns the length (in bytes, excluding the null terminator) of `src` but + * never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); + +/** + * Copy a string. + * + * This function copies up to `maxlen` - 1 characters from `src` to `dst`, + * then appends a null terminator. + * + * If `maxlen` is 0, no characters are copied and no null terminator is + * written. + * + * If you want to copy an UTF-8 string but need to ensure that multi-byte + * sequences are not truncated, consider using SDL_utf8strlcpy(). + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated string to copy. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcat + * \sa SDL_utf8strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Copy an UTF-8 string. + * + * This function copies up to `dst_bytes` - 1 bytes from `src` to `dst` while + * also ensuring that the string written to `dst` does not end in a truncated + * multi-byte sequence. Finally, it appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * Note that unlike SDL_strlcpy(), this function returns the number of bytes + * written, not the length of `src`. + * + * \param dst The destination buffer. Must not be NULL, and must not overlap + * with `src`. + * \param src The null-terminated UTF-8 string to copy. Must not be NULL, and + * must not overlap with `dst`. + * \param dst_bytes The length (in bytes) of the destination buffer. Must not + * be 0. + * \returns the number of bytes written, excluding the null terminator. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char *dst, const char *src, size_t dst_bytes); + +/** + * Concatenate strings. + * + * This function appends up to `maxlen` - SDL_strlen(dst) - 1 characters from + * `src` to the end of the string in `dst`, then appends a null terminator. + * + * `src` and `dst` must not overlap. + * + * If `maxlen` - SDL_strlen(dst) - 1 is less than or equal to 0, then `dst` is + * unmodified. + * + * \param dst The destination buffer already containing the first + * null-terminated string. Must not be NULL and must not overlap + * with `src`. + * \param src The second null-terminated string. Must not be NULL, and must + * not overlap with `dst`. + * \param maxlen The length (in characters) of the destination buffer. + * \returns the length (in characters, excluding the null terminator) of the + * string in `dst` plus the length of `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_strlcpy + */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + +/** + * Allocate a copy of a string. + * + * This allocates enough space for a null-terminated copy of `str`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); + +/** + * Allocate a copy of a string, up to n characters. + * + * This allocates enough space for a null-terminated copy of `str`, up to + * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into + * this space. + * + * If the string is longer than `maxlen` bytes, the returned string will be + * `maxlen` bytes long, plus a null-terminator character that isn't included + * in the count. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \param maxlen the maximum length of the copied string, not counting the + * null-terminator character. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); + +/** + * Reverse a string's contents. + * + * This reverses a null-terminated string in-place. Only the content of the + * string is reversed; the null-terminator character remains at the end of the + * reversed string. + * + * **WARNING**: This function reverses the _bytes_ of the string, not the + * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this + * will ruin the string data. You should only use this function on strings + * that are completely comprised of low ASCII characters. + * + * \param str the string to reverse. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -1122,7 +3183,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strlwr */ @@ -1143,34 +3204,592 @@ extern SDL_DECLSPEC char * SDLCALL SDL_strupr(char *str); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_strupr */ extern SDL_DECLSPEC char * SDLCALL SDL_strlwr(char *str); +/** + * Search a string for the first instance of a specific byte. + * + * The search ends once it finds the requested byte value, or a null + * terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the first instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strchr(const char *str, int c); + +/** + * Search a string for the last instance of a specific byte. + * + * The search must go until it finds a null terminator byte to end the string. + * + * Note that this looks for _bytes_, not _characters_, so you cannot match + * against a Unicode codepoint > 255, regardless of character encoding. + * + * \param str the string to search. Must not be NULL. + * \param c the byte value to search for. + * \returns a pointer to the last instance of `c` in the string, or NULL if + * not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrchr(const char *str, int c); + +/** + * Search a string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strstr(const char *haystack, const char *needle); + +/** + * Search a string, up to n bytes, for the first instance of a specific + * substring. + * + * The search ends once it finds the requested substring, or a null terminator + * byte to end the string, or `maxlen` bytes have been examined. It is + * possible to use this function on a string without a null terminator. + * + * Note that this looks for strings of _bytes_, not _characters_, so it's + * legal to search for malformed and incomplete UTF-8 sequences. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \param maxlen the maximum number of bytes to search in `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen); + +/** + * Search a UTF-8 string for the first instance of a specific substring, + * case-insensitively. + * + * This will work with Unicode strings, using a technique called + * "case-folding" to handle the vast majority of case-sensitive human + * languages regardless of system locale. It can deal with expanding values: a + * German Eszett character can compare against two ASCII 's' chars and be + * considered a match, for example. A notable exception: it does not handle + * the Turkish 'i' character; human language is complicated! + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), which is to say two strings of random bits may turn out to + * match if they convert to the same amount of replacement characters. + * + * \param haystack the string to search. Must not be NULL. + * \param needle the string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL + * if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strcasestr(const char *haystack, const char *needle); -extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr); + +/** + * This works exactly like strtok_r() but doesn't require access to a C + * runtime. + * + * Break a string up into a series of tokens. + * + * To start tokenizing a new string, `str` should be the non-NULL address of + * the string to start tokenizing. Future calls to get the next token from the + * same string should specify a NULL. + * + * Note that this function will overwrite pieces of `str` with null chars to + * split it into tokens. This function cannot be used with const/read-only + * strings! + * + * `saveptr` just needs to point to a `char *` that can be overwritten; SDL + * will use this to save tokenizing state between calls. It is initialized if + * `str` is non-NULL, and used to resume tokenizing when `str` is NULL. + * + * \param str the string to tokenize, or NULL to continue tokenizing. + * \param delim the delimiter string that separates tokens. + * \param saveptr pointer to a char *, used for ongoing state. + * \returns A pointer to the next token, or NULL if no tokens remain. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strtok_r(char *str, const char *delim, char **saveptr); + +/** + * Count the number of codepoints in a UTF-8 string. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strlen(). + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \returns The length (in codepoints, excluding the null terminator) of + * `src`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strnlen + * \sa SDL_strlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str); + +/** + * Count the number of codepoints in a UTF-8 string, up to n bytes. + * + * Counts the _codepoints_, not _bytes_, in `str`, excluding the null + * terminator. + * + * If you need to count the bytes in a string instead, consider using + * SDL_strnlen(). + * + * The counting stops at `bytes` bytes (not codepoints!). This seems + * counterintuitive, but makes it easy to express the total size of the + * string's buffer. + * + * Since this handles Unicode, it expects the strings to be well-formed UTF-8 + * and not a null-terminated string of arbitrary bytes. Bytes that are not + * valid UTF-8 are treated as Unicode character U+FFFD (REPLACEMENT + * CHARACTER), so a malformed or incomplete UTF-8 sequence might increase the + * count by several replacement characters. + * + * \param str The null-terminated UTF-8 string to read. Must not be NULL. + * \param bytes The maximum amount of bytes to count. + * \returns The length (in codepoints, excluding the null terminator) of `src` + * but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_utf8strlen + * \sa SDL_strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strnlen(const char *str, size_t bytes); +/** + * Convert an integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_uitoa + * \sa SDL_ltoa + * \sa SDL_lltoa + */ extern SDL_DECLSPEC char * SDLCALL SDL_itoa(int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(Sint64 value, char *str, int radix); -extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(Uint64 value, char *str, int radix); +/** + * Convert an unsigned integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_itoa + * \sa SDL_ultoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_uitoa(unsigned int value, char *str, int radix); + +/** + * Convert a long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ultoa + * \sa SDL_itoa + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ltoa(long value, char *str, int radix); + +/** + * Convert an unsigned long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ltoa + * \sa SDL_uitoa + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ultoa(unsigned long value, char *str, int radix); + +#ifndef SDL_NOLONGLONG + +/** + * Convert a long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget possible negative + * signs, null terminator bytes, etc). + * + * \param value the long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ulltoa + * \sa SDL_itoa + * \sa SDL_ltoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_lltoa(long long value, char *str, int radix); + +/** + * Convert an unsigned long long integer into a string. + * + * This requires a radix to specified for string format. Specifying 10 + * produces a decimal number, 16 hexidecimal, etc. Must be in the range of 2 + * to 36. + * + * Note that this function will overflow a buffer if `str` is not large enough + * to hold the output! It may be safer to use SDL_snprintf to clamp output, or + * SDL_asprintf to allocate a buffer. Otherwise, it doesn't hurt to allocate + * much more space than you expect to use (and don't forget null terminator + * bytes, etc). + * + * \param value the unsigned long long integer to convert. + * \param str the buffer to write the string into. + * \param radix the radix to use for string generation. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_lltoa + * \sa SDL_uitoa + * \sa SDL_ultoa + */ +extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *str, int radix); +#endif + +/** + * Parse an `int` from a string. + * + * The result of calling `SDL_atoi(str)` is equivalent to + * `(int)SDL_strtol(str, NULL, 10)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `int`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_itoa + */ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); + +/** + * Parse a `double` from a string. + * + * The result of calling `SDL_atof(str)` is equivalent to `SDL_strtod(str, + * NULL)`. + * + * \param str The null-terminated string to read. Must not be NULL. + * \returns the parsed `double`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + */ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); + +/** + * Parse a `long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long`, the result is clamped to + * the minimum and maximum representable `long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtoul + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ltoa + * \sa SDL_wcstol + */ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long`, the result is + * clamped to the maximum representable `unsigned long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_ultoa + */ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **endp, int base); -extern SDL_DECLSPEC Sint64 SDLCALL SDL_strtoll(const char *str, char **endp, int base); -extern SDL_DECLSPEC Uint64 SDLCALL SDL_strtoull(const char *str, char **endp, int base); + +#ifndef SDL_NOLONGLONG + +/** + * Parse a `long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside a `long long`, the result is + * clamped to the minimum and maximum representable `long long` values. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `long long`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoul + * \sa SDL_strtoull + * \sa SDL_strtod + * \sa SDL_lltoa + */ +extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, int base); + +/** + * Parse an `unsigned long long` from a string. + * + * If `str` starts with whitespace, then those whitespace characters are + * skipped before attempting to parse the number. + * + * If the parsed number does not fit inside an `unsigned long long`, the + * result is clamped to the maximum representable `unsigned long long` value. + * + * \param str The null-terminated string to read. Must not be NULL. + * \param endp If not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \param base The base of the integer to read. Supported values are 0 and 2 + * to 36 inclusive. If 0, the base will be inferred from the + * number's prefix (0x for hexadecimal, 0 for octal, decimal + * otherwise). + * \returns the parsed `unsigned long long`, or 0 if no number could be + * parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtod + * \sa SDL_ulltoa + */ +extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, char **endp, int base); +#endif + +/** + * Parse a `double` from a string. + * + * This function makes fewer guarantees than the C runtime `strtod`: + * + * - Only decimal notation is guaranteed to be supported. The handling of + * scientific and hexadecimal notation is unspecified. + * - Whether or not INF and NAN can be parsed is unspecified. + * - The precision of the result is unspecified. + * + * \param str the null-terminated string to read. Must not be NULL. + * \param endp if not NULL, the address of the first invalid character (i.e. + * the next character after the parsed number) will be written to + * this pointer. + * \returns the parsed `double`, or 0 if no number could be parsed. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_atoi + * \sa SDL_atof + * \sa SDL_strtol + * \sa SDL_strtoll + * \sa SDL_strtoul + * \sa SDL_strtoull + */ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); /** @@ -1189,7 +3808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_strtod(const char *str, char **endp); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); @@ -1219,7 +3838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcmp(const char *str1, const char *str2); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, size_t maxlen); @@ -1247,7 +3866,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncmp(const char *str1, const char *str2, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2); @@ -1287,20 +3906,39 @@ extern SDL_DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t maxlen); +/** + * Searches a string for the first occurence of any character contained in a + * breakset, and returns a pointer from the string to that character. + * + * \param str The null-terminated string to be searched. Must not be NULL, and + * must not overlap with `breakset`. + * \param breakset A null-terminated string containing the list of characters + * to look for. Must not be NULL, and must not overlap with + * `str`. + * \returns A pointer to the location, in str, of the first occurence of a + * character present in the breakset, or NULL if none is found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC char * SDLCALL SDL_strpbrk(const char *str, const char *breakset); + /** * The Unicode REPLACEMENT CHARACTER codepoint. * - * SDL_StepUTF8() reports this codepoint when it encounters a UTF-8 string - * with encoding errors. + * SDL_StepUTF8() and SDL_StepBackUTF8() report this codepoint when they + * encounter a UTF-8 string with encoding errors. * * This tends to render as something like a question mark in most places. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. * + * \sa SDL_StepBackUTF8 * \sa SDL_StepUTF8 */ #define SDL_INVALID_UNICODE_CODEPOINT 0xFFFD @@ -1346,10 +3984,41 @@ extern SDL_DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *st * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen); +/** + * Decode a UTF-8 string in reverse, one Unicode codepoint at a time. + * + * This will go to the start of the previous Unicode codepoint in the string, + * move `*pstr` to that location and return that codepoint. + * + * If `*pstr` is already at the start of the string), it will not advance + * `*pstr` at all. + * + * Generally this function is called in a loop until it returns zero, + * adjusting its parameter each iteration. + * + * If an invalid UTF-8 sequence is encountered, this function returns + * SDL_INVALID_UNICODE_CODEPOINT. + * + * Several things can generate invalid UTF-8 sequences, including overlong + * encodings, the use of UTF-16 surrogate values, and truncated data. Please + * refer to + * [RFC3629](https://www.ietf.org/rfc/rfc3629.txt) + * for details. + * + * \param start a pointer to the beginning of the UTF-8 string. + * \param pstr a pointer to a UTF-8 string pointer to be read and adjusted. + * \returns the previous Unicode codepoint in the string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const char **pstr); + /** * Convert a single Unicode codepoint to UTF-8. * @@ -1375,18 +4044,200 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepUTF8(const char **pstr, size_t *pslen * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); - +/** + * This works exactly like sscanf() but doesn't require access to a C runtime. + * + * Scan a string, matching a format string, converting each '%' item and + * storing it to pointers provided through variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); + +/** + * This works exactly like vsscanf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_sscanf(), except it takes a `va_list` instead + * of using `...` variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` of pointers to values to be filled in with scanned + * items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); -extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); -extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like snprintf() but doesn't require access to a C + * runtime. + * + * Format a string of up to `maxlen`-1 bytes, converting each '%' item with + * values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * bytes will be written at all. + * + * This function returns the number of _bytes_ (not _characters_) that should + * be written, excluding the null-terminator character. If this returns a + * number >= `maxlen`, it means the output string was truncated. A negative + * return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * This works exactly like swprintf() but doesn't require access to a C + * runtime. + * + * Format a wide string of up to `maxlen`-1 wchar_t values, converting each + * '%' item with values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, this + * function null-terminates the output, by treating the null-terminator as + * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide + * characters will be written at all. + * + * This function returns the number of _wide characters_ (not _codepoints_) + * that should be written, excluding the null-terminator character. If this + * returns a number >= `maxlen`, it means the output string was truncated. A + * negative return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the wide string into. Must not be NULL. + * \param maxlen the maximum wchar_t values to write, including the + * null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like vsnprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); -extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); + +/** + * This works exactly like vswprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_swprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum wide characters to write, including the + * null-terminator. + * \param fmt a printf-style format wide string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like asprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_snprintf(), except it allocates a buffer large + * enough to hold the output string on behalf of the caller. + * + * On success, this function returns the number of bytes (not characters) + * comprising the output string, not counting the null-terminator character, + * and sets `*strp` to the newly-allocated string. + * + * On error, this function returns a negative number, and the value of `*strp` + * is undefined. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * This works exactly like vasprintf() but doesn't require access to a C + * runtime. + * + * Functions identically to SDL_asprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** @@ -1401,7 +4252,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STR * \threadsafety This should be called on the same thread that calls * SDL_rand*() * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits @@ -1436,7 +4287,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_randf @@ -1459,7 +4310,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand(Sint32 n); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_srand * \sa SDL_rand @@ -1481,7 +4332,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf(void); * * \threadsafety All calls should be made from a single thread * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_randf @@ -1516,7 +4367,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand * \sa SDL_rand_bits_r @@ -1543,7 +4394,7 @@ extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_r(Uint64 *state, Sint32 n); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_bits_r * \sa SDL_rand_r @@ -1569,18 +4420,34 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state); * \threadsafety This function is thread-safe, as long as the state pointer * isn't shared between threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_rand_r * \sa SDL_randf_r */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); - #ifndef SDL_PI_D + +/** + * The value of Pi, as a double-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_F + */ #define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */ #endif + #ifndef SDL_PI_F + +/** + * The value of Pi, as a single-precision floating point literal. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PI_D + */ #define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */ #endif @@ -1606,7 +4473,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acosf * \sa SDL_asin @@ -1636,7 +4503,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_acos * \sa SDL_asinf @@ -1666,7 +4533,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asinf * \sa SDL_acos @@ -1696,7 +4563,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_asin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_asin * \sa SDL_acosf @@ -1728,7 +4595,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atanf * \sa SDL_atan2 @@ -1760,7 +4627,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan * \sa SDL_atan2f @@ -1796,7 +4663,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1832,7 +4699,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_atan2f * \sa SDL_atan @@ -1858,7 +4725,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceilf * \sa SDL_floor @@ -1886,7 +4753,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ceil * \sa SDL_floorf @@ -1915,7 +4782,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabs @@ -1941,7 +4808,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_copysignf * \sa SDL_fabsf @@ -1968,7 +4835,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cosf * \sa SDL_acos @@ -1996,7 +4863,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_cos * \sa SDL_acosf @@ -2029,7 +4896,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_expf * \sa SDL_log @@ -2061,7 +4928,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_exp * \sa SDL_logf @@ -2083,7 +4950,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabsf */ @@ -2104,7 +4971,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fabs */ @@ -2128,7 +4995,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floorf * \sa SDL_ceil @@ -2156,7 +5023,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_floor * \sa SDL_ceilf @@ -2184,7 +5051,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_truncf * \sa SDL_fmod @@ -2213,7 +5080,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_trunc * \sa SDL_fmodf @@ -2242,7 +5109,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmodf * \sa SDL_modf @@ -2272,7 +5139,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_fmod * \sa SDL_truncf @@ -2292,7 +5159,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinff */ @@ -2306,7 +5173,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinf(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isinf */ @@ -2320,7 +5187,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isinff(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnanf */ @@ -2334,7 +5201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_isnan */ @@ -2362,7 +5229,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isnanf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_logf * \sa SDL_log10 @@ -2392,7 +5259,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log * \sa SDL_expf @@ -2421,7 +5288,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10f * \sa SDL_log @@ -2451,7 +5318,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_log10 * \sa SDL_logf @@ -2471,7 +5338,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modff * \sa SDL_trunc @@ -2491,7 +5358,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_modf * \sa SDL_truncf @@ -2523,7 +5390,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_powf * \sa SDL_exp @@ -2555,7 +5422,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_pow * \sa SDL_expf @@ -2582,7 +5449,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_roundf * \sa SDL_lround @@ -2611,7 +5478,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_round * \sa SDL_lroundf @@ -2640,7 +5507,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lroundf * \sa SDL_round @@ -2669,7 +5536,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_lround * \sa SDL_roundf @@ -2697,7 +5564,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbnf * \sa SDL_pow @@ -2722,7 +5589,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_scalbn * \sa SDL_powf @@ -2749,7 +5616,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sinf * \sa SDL_asin @@ -2765,7 +5632,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * Range: `-1 <= y <= 1` * * This function operates on single-precision floating point values, use - * SDL_sinf for double-precision floats. + * SDL_sin for double-precision floats. * * This function may use a different approximation across different versions, * platforms and configurations. i.e, it can return a different value given @@ -2777,7 +5644,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sin * \sa SDL_asinf @@ -2805,7 +5672,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrtf */ @@ -2831,7 +5698,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_sqrt */ @@ -2857,7 +5724,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tanf * \sa SDL_sin @@ -2887,7 +5754,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_tan * \sa SDL_sinf @@ -2897,12 +5764,13 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x); */ extern SDL_DECLSPEC float SDLCALL SDL_tanf(float x); -/* The SDL implementation of iconv() returns these error codes */ -#define SDL_ICONV_ERROR (size_t)-1 -#define SDL_ICONV_E2BIG (size_t)-2 -#define SDL_ICONV_EILSEQ (size_t)-3 -#define SDL_ICONV_EINVAL (size_t)-4 - +/** + * An opaque handle representing string encoding conversion state. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_iconv_open + */ typedef struct SDL_iconv_data_t *SDL_iconv_t; /** @@ -2914,7 +5782,7 @@ typedef struct SDL_iconv_data_t *SDL_iconv_t; * \returns a handle that must be freed with SDL_iconv_close, or * SDL_ICONV_ERROR on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_close @@ -2929,7 +5797,7 @@ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode, * \param cd The character set conversion handle. * \returns 0 on success, or -1 on failure. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv * \sa SDL_iconv_open @@ -2941,7 +5809,22 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * This function converts text between encodings, reading from and writing to * a buffer. * - * It returns the number of succesful conversions. + * It returns the number of succesful conversions on success. On error, + * SDL_ICONV_E2BIG is returned when the output buffer is too small, or + * SDL_ICONV_EILSEQ is returned when an invalid input sequence is encountered, + * or SDL_ICONV_EINVAL is returned when an incomplete input sequence is + * encountered. + * + * On exit: + * + * - inbuf will point to the beginning of the next multibyte sequence. On + * error, this is the location of the problematic input sequence. On + * success, this is the end of the input sequence. + * - inbytesleft will be set to the number of bytes left to convert, which + * will be 0 on success. + * - outbuf will point to the location where to store the next output byte. + * - outbytesleft will be set to the number of bytes left in the output + * buffer. * * \param cd The character set conversion context, created in * SDL_iconv_open(). @@ -2950,23 +5833,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd); * \param inbytesleft The number of bytes in the input buffer. * \param outbuf Address of variable that points to the output buffer. * \param outbytesleft The number of bytes in the output buffer. - * \returns the number of conversions on success, else SDL_ICONV_E2BIG is - * returned when the output buffer is too small, or SDL_ICONV_EILSEQ - * is returned when an invalid input sequence is encountered, or - * SDL_ICONV_EINVAL is returned when an incomplete input sequence is - * encountered. + * \returns the number of conversions on success, or a negative error code. * - * On exit: - * - * - inbuf will point to the beginning of the next multibyte - * sequence. On error, this is the location of the problematic - * input sequence. On success, this is the end of the input - * sequence. - inbytesleft will be set to the number of bytes left - * to convert, which will be 0 on success. - outbuf will point to - * the location where to store the next output byte. - outbytesleft - * will be set to the number of bytes left in the output buffer. - * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -2976,6 +5845,12 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); +#define SDL_ICONV_ERROR (size_t)-1 /**< Generic error. Check SDL_GetError()? */ +#define SDL_ICONV_E2BIG (size_t)-2 /**< Output buffer was too small. */ +#define SDL_ICONV_EILSEQ (size_t)-3 /**< Invalid input sequence was encountered. */ +#define SDL_ICONV_EINVAL (size_t)-4 /**< Incomplete input sequence was encountered. */ + + /** * Helper function to convert a string's encoding in one call. * @@ -2995,7 +5870,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf, * \param inbytesleft the size of the input string _in bytes_. * \returns a new string, converted to the new encoding, or NULL on error. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_iconv_open * \sa SDL_iconv_close @@ -3006,12 +5881,65 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode, const char *inbuf, size_t inbytesleft); -/* Some helper macros for common cases... */ +/* Some helper macros for common SDL_iconv_string cases... */ + +/** + * Convert a UTF-8 string to the current locale's character encoding. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-2. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a UTF-8 string to UCS-4. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1) + +/** + * Convert a wchar_t string to UTF-8. + * + * This is a helper macro that might be more clear than calling + * SDL_iconv_string directly. However, it double-evaluates its parameter, so + * do not use an expression with side-effects here. + * + * \param S the string to convert. + * \returns a new string, converted to the new encoding, or NULL on error. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t)) + /* force builds using Clang's static analysis tools to use literal C runtime here, since there are possibly tests that are ineffective otherwise. */ #if defined(__clang_analyzer__) && !defined(SDL_DISABLE_ANALYZE_MACROS) @@ -3034,6 +5962,9 @@ size_t wcslcpy(wchar_t *dst, const wchar_t *src, size_t size); size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #endif +/* strdup is not ANSI but POSIX, and its prototype might be hidden... */ +char *strdup(const char *str); + /* Starting LLVM 16, the analyser errors out if these functions do not have their prototype defined (clang-diagnostic-implicit-function-declaration) */ #include @@ -3073,6 +6004,7 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); #define SDL_wcsncmp wcsncmp #define SDL_strcasecmp strcasecmp #define SDL_strncasecmp strncasecmp +#define SDL_strpbrk strpbrk #define SDL_sscanf sscanf #define SDL_vsscanf vsscanf #define SDL_snprintf snprintf @@ -3082,29 +6014,27 @@ size_t wcslcat(wchar_t *dst, const wchar_t *src, size_t size); /** * Multiply two integers, checking for overflow. * - * If `a * b` would overflow, return -1. + * If `a * b` would overflow, return false. * - * Otherwise store `a * b` via ret and return 0. + * Otherwise store `a * b` via ret and return true. * * \param a the multiplicand. * \param b the multiplier. - * \param ret on non-overflow output, stores the multiplication result. May + * \param ret on non-overflow output, stores the multiplication result, may * not be NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is multiplied without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow(size_t a, size_t b, size_t *ret) { if (a != 0 && b > SDL_SIZE_MAX / a) { - return -1; + return false; } *ret = a * b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION @@ -3112,60 +6042,72 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a, /* This needs to be wrapped in an inline rather than being a direct #define, * because __builtin_mul_overflow() is type-generic, but we want to be * consistent about interpreting a and b as size_t. */ -SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_mul_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_mul_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_mul_overflow(a, b, ret) == 0); } -#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret)) +#define SDL_size_mul_check_overflow(a, b, ret) SDL_size_mul_check_overflow_builtin(a, b, ret) #endif #endif /** * Add two integers, checking for overflow. * - * If `a + b` would overflow, return -1. + * If `a + b` would overflow, return false. * - * Otherwise store `a + b` via ret and return 0. + * Otherwise store `a + b` via ret and return true. * * \param a the first addend. * \param b the second addend. - * \param ret on non-overflow output, stores the addition result. May not be + * \param ret on non-overflow output, stores the addition result, may not be * NULL. - * \returns -1 on overflow, 0 if result doesn't overflow. + * \returns false on overflow, true if result is added without overflow. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow(size_t a, size_t b, size_t *ret) { if (b > SDL_SIZE_MAX - a) { - return -1; + return false; } *ret = a + b; - return 0; + return true; } #ifndef SDL_WIKI_DOCUMENTATION_SECTION #if SDL_HAS_BUILTIN(__builtin_add_overflow) /* This needs to be wrapped in an inline rather than being a direct #define, * the same as the call to __builtin_mul_overflow() above. */ -SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a, - size_t b, - size_t *ret) +SDL_FORCE_INLINE bool SDL_size_add_check_overflow_builtin(size_t a, size_t b, size_t *ret) { - return __builtin_add_overflow(a, b, ret) == 0 ? 0 : -1; + return (__builtin_add_overflow(a, b, ret) == 0); } -#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret)) +#define SDL_size_add_check_overflow(a, b, ret) SDL_size_add_check_overflow_builtin(a, b, ret) #endif #endif /* This is a generic function pointer which should be cast to the type you expect */ -#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A generic function pointer. + * + * In theory, generic function pointers should use this, instead of `void *`, + * since some platforms could treat code addresses differently than data + * addresses. Although in current times no popular platforms make this + * distinction, it is more correct and portable to use the correct type for a + * generic pointer. + * + * If for some reason you need to force this typedef to be an actual `void *`, + * perhaps to work around a compiler or existing code, you can define + * `SDL_FUNCTION_POINTER_IS_VOID_POINTER` before including any SDL headers. + * + * \since This datatype is available since SDL 3.2.0. + */ +typedef void (*SDL_FunctionPointer)(void); +#elif defined(SDL_FUNCTION_POINTER_IS_VOID_POINTER) typedef void *SDL_FunctionPointer; #else typedef void (*SDL_FunctionPointer)(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h index 91a90bc..8b89ace 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_storage.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,222 @@ /** * # CategoryStorage * - * SDL storage container management. + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) { + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(data); + * } + * } + * } + * + * void ReadSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * + * void WriteSave(void) + * { + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == NULL) { + * // Something bad happened! + * } else { + * // A bunch of stuff happens here + * fclose(save); + * } + * } + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * { + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(NULL, 0); + * if (title == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(title)) { + * SDL_Delay(1); + * } + * + * for (size_t i = 0; i < numFiles; i += 1) { + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) { + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * } + * + * SDL_CloseStorage(title); + * } + * + * void ReadSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) { + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) { + * // A bunch of stuff happens here + * } else { + * // Something bad happened! + * } + * SDL_free(dst); + * } else { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * + * void WriteSave(void) + * { + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == NULL) { + * // Something bad happened! + * } + * while (!SDL_StorageReady(user)) { + * SDL_Delay(1); + * } + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) { + * // Something bad happened! + * } + * + * SDL_CloseStorage(user); + * } + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the NULL terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. */ #ifndef SDL_storage_h_ @@ -40,8 +255,6 @@ extern "C" { #endif -/* !!! FIXME: Don't let this ship without async R/W support!!! */ - /** * Function interface for SDL_Storage. * @@ -52,44 +265,61 @@ extern "C" { * It is not usually necessary to do this; SDL provides standard * implementations for many things you might expect to do with an SDL_Storage. * - * \since This struct is available since SDL 3.0.0. + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE */ typedef struct SDL_StorageInterface { + /* The version of this interface */ + Uint32 version; + /* Called when the storage is closed */ - SDL_bool (SDLCALL *close)(void *userdata); + bool (SDLCALL *close)(void *userdata); /* Optional, returns whether the storage is currently ready for access */ - SDL_bool (SDLCALL *ready)(void *userdata); + bool (SDLCALL *ready)(void *userdata); /* Enumerate a directory, optional for write-only storage */ - SDL_bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); + bool (SDLCALL *enumerate)(void *userdata, const char *path, SDL_EnumerateDirectoryCallback callback, void *callback_userdata); /* Get path information, optional for write-only storage */ - SDL_bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); + bool (SDLCALL *info)(void *userdata, const char *path, SDL_PathInfo *info); /* Read a file from storage, optional for write-only storage */ - SDL_bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); + bool (SDLCALL *read_file)(void *userdata, const char *path, void *destination, Uint64 length); /* Write a file to storage, optional for read-only storage */ - SDL_bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); + bool (SDLCALL *write_file)(void *userdata, const char *path, const void *source, Uint64 length); /* Create a directory, optional for read-only storage */ - SDL_bool (SDLCALL *mkdir)(void *userdata, const char *path); + bool (SDLCALL *mkdir)(void *userdata, const char *path); /* Remove a file or empty directory, optional for read-only storage */ - SDL_bool (SDLCALL *remove)(void *userdata, const char *path); + bool (SDLCALL *remove)(void *userdata, const char *path); /* Rename a path, optional for read-only storage */ - SDL_bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *rename)(void *userdata, const char *oldpath, const char *newpath); /* Copy a file, optional for read-only storage */ - SDL_bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); + bool (SDLCALL *copy)(void *userdata, const char *oldpath, const char *newpath); /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); } SDL_StorageInterface; +/* Check the size of SDL_StorageInterface + * + * If this assert fails, either the compiler is padding to an unexpected size, + * or the interface has been updated and this should be updated to match and + * the code using this interface should be updated to handle the old version. + */ +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); + /** * An abstract interface for filesystem access. * @@ -97,7 +327,7 @@ typedef struct SDL_StorageInterface * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create * an object with a custom implementation using SDL_OpenStorage. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_Storage SDL_Storage; @@ -109,7 +339,7 @@ typedef struct SDL_Storage SDL_Storage; * \returns a title storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -132,7 +362,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenTitleStorage(const char *overr * \returns a user storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -156,7 +386,7 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenUserStorage(const char *org, c * \returns a filesystem storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize @@ -176,16 +406,21 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenFileStorage(const char *path); * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() * or SDL_OpenUserStorage(). * - * \param iface the function table to be used by this container. - * \param userdata the pointer that will be passed to the store interface. + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the pointer that will be passed to the interface functions. * \returns a storage container on success or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseStorage * \sa SDL_GetStorageFileSize * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE * \sa SDL_ReadStorageFile * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -196,33 +431,33 @@ extern SDL_DECLSPEC SDL_Storage * SDLCALL SDL_OpenStorage(const SDL_StorageInter * Closes and frees a storage container. * * \param storage a storage container to close. - * \returns SDL_TRUE if the container was freed with no errors, SDL_FALSE - * otherwise; call SDL_GetError() for more information. Even if the - * function returns an error, the container data will be freed; the - * error is only for informational purposes. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_OpenFileStorage * \sa SDL_OpenStorage * \sa SDL_OpenTitleStorage * \sa SDL_OpenUserStorage */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_CloseStorage(SDL_Storage *storage); /** * Checks if the storage container is ready to use. * - * This function should be called in regular intervals until it returns - * SDL_TRUE - however, it is not recommended to spinwait on this call, as the - * backend may depend on a synchronous message loop. + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. * * \param storage a storage container to query. - * \returns SDL_TRUE if the container is ready, SDL_FALSE otherwise. + * \returns true if the container is ready, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); +extern SDL_DECLSPEC bool SDLCALL SDL_StorageReady(SDL_Storage *storage); /** * Query the size of a file within a storage container. @@ -230,34 +465,38 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage); * \param storage a storage container to query. * \param path the relative path of the file to query. * \param length a pointer to be filled with the file's length. - * \returns SDL_TRUE if the file could be queried or SDL_FALSE on failure; - * call SDL_GetError() for more information. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, const char *path, Uint64 *length); /** * Synchronously read a file from a storage container into a client-provided * buffer. * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * * \param storage a storage container to read from. * \param path the relative path of the file to read. * \param destination a client-provided buffer to read the file into. * \param length the length of the destination buffer. - * \returns SDL_TRUE if the file was read or SDL_FALSE on failure; call - * SDL_GetError() for more information. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageFileSize * \sa SDL_StorageReady * \sa SDL_WriteStorageFile */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const char *path, void *destination, Uint64 length); /** * Synchronously write a file from client memory into a storage container. @@ -266,64 +505,73 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, c * \param path the relative path of the file to write. * \param source a client-provided buffer to write from. * \param length the length of the source buffer. - * \returns SDL_TRUE if the file was written or SDL_FALSE on failure; call + * \returns true if the file was written or false on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetStorageSpaceRemaining * \sa SDL_ReadStorageFile * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteStorageFile(SDL_Storage *storage, const char *path, const void *source, Uint64 length); /** * Create a directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to create. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_CreateStorageDirectory(SDL_Storage *storage, const char *path); /** * Enumerate a directory in a storage container through a callback function. * * This function provides every directory entry through an app-provided * callback, called once for each directory entry, until all results have been - * provided or the callback returns <= 0. + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param callback a function that is called for each entry in the directory. * \param userdata a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateStorageDirectory(SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata); /** * Remove a file or an empty directory in a writable storage container. * * \param storage a storage container. * \param path the path of the directory to enumerate. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, const char *path); /** * Rename a file or directory in a writable storage container. @@ -331,14 +579,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Copy a file in a writable storage container. @@ -346,14 +594,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RenameStoragePath(SDL_Storage *storage, * \param storage a storage container. * \param oldpath the old path. * \param newpath the new path. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); +extern SDL_DECLSPEC bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, const char *oldpath, const char *newpath); /** * Get information about a filesystem path in a storage container. @@ -362,14 +610,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_CopyStorageFile(SDL_Storage *storage, c * \param path the path to query. * \param info a pointer filled in with information about the path, or NULL to * check for the existence of a file. - * \returns SDL_TRUE on success or SDL_FALSE if the file doesn't exist, or - * another failure; call SDL_GetError() for more information. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); +extern SDL_DECLSPEC bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage, const char *path, SDL_PathInfo *info); /** * Queries the remaining space in a storage container. @@ -377,7 +625,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetStoragePathInfo(SDL_Storage *storage * \param storage a storage container to query. * \returns the amount of remaining space, in bytes. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_StorageReady * \sa SDL_WriteStorageFile @@ -401,8 +649,11 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * + * If `path` is NULL, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * * \param storage a storage container. - * \param path the path of the directory to enumerate. + * \param path the path of the directory to enumerate, or NULL for the root. * \param pattern the pattern that files in the directory must match. Can be * NULL. * \param flags `SDL_GLOB_*` bitflags that affect this search. @@ -417,7 +668,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * \threadsafety It is safe to call this function from any thread, assuming * the `storage` object is thread-safe. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC char ** SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h index aafe574..0752f53 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_surface.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,19 @@ /** * # CategorySurface * - * SDL_Surface definition and management functions. + * SDL surfaces are buffers of pixels in system RAM. These are useful for + * passing around and manipulating images that are not stored in GPU memory. + * + * SDL_Surface makes serious efforts to manage images in various formats, and + * provides a reasonable toolbox for transforming the data, including copying + * between surfaces, filling rectangles in the image data, etc. + * + * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not + * provide loaders for various other file formats, but there are several + * excellent external libraries that do, including its own satellite library, + * SDL_image: + * + * https://github.com/libsdl-org/SDL_image */ #ifndef SDL_surface_h_ @@ -47,7 +59,7 @@ extern "C" { * * These are generally considered read-only. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_SurfaceFlags; @@ -59,14 +71,14 @@ typedef Uint32 SDL_SurfaceFlags; /** * Evaluates to true if the surface needs to be locked before access. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MUSTLOCK(S) ((((S)->flags & SDL_SURFACE_LOCK_NEEDED)) == SDL_SURFACE_LOCK_NEEDED) /** * The scaling mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ScaleMode { @@ -77,7 +89,7 @@ typedef enum SDL_ScaleMode /** * The flip mode. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlipMode { @@ -86,8 +98,7 @@ typedef enum SDL_FlipMode SDL_FLIP_VERTICAL /**< flip vertically */ } SDL_FlipMode; -/* Internal surface data */ -typedef struct SDL_SurfaceData SDL_SurfaceData; +#ifndef SDL_INTERNAL /** * A collection of pixels used in software blitting. @@ -104,22 +115,32 @@ typedef struct SDL_SurfaceData SDL_SurfaceData; * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * - * \since This struct is available since SDL 3.0.0. + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateSurface + * \sa SDL_DestroySurface */ -typedef struct SDL_Surface +struct SDL_Surface { - SDL_SurfaceFlags flags; /**< Read-only */ - SDL_PixelFormat format; /**< Read-only */ - int w, h; /**< Read-only */ - int pitch; /**< Read-only */ - void *pixels; /**< Read-only pointer, writable pixels if non-NULL */ + SDL_SurfaceFlags flags; /**< The flags of the surface, read-only */ + SDL_PixelFormat format; /**< The format of the surface, read-only */ + int w; /**< The width of the surface, read-only. */ + int h; /**< The height of the surface, read-only. */ + int pitch; /**< The distance in bytes between rows of pixels, read-only */ + void *pixels; /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */ int refcount; /**< Application reference count, used when freeing surface */ - SDL_SurfaceData *internal; /**< Private */ - -} SDL_Surface; + void *reserved; /**< Reserved for internal use */ +}; +#endif /* !SDL_INTERNAL */ +typedef struct SDL_Surface SDL_Surface; /** * Allocate a new surface with a specific pixel format. @@ -132,7 +153,7 @@ typedef struct SDL_Surface * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurfaceFrom * \sa SDL_DestroySurface @@ -160,7 +181,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurface(int width, int heigh * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -174,9 +195,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_CreateSurfaceFrom(int width, int h * * \param surface the SDL_Surface to free. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_CreateStackSurface * \sa SDL_CreateSurface * \sa SDL_CreateSurfaceFrom */ @@ -206,7 +226,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface); @@ -221,16 +241,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac * interpreted in color operations. * * \param surface the SDL_Surface structure to update. - * \param colorspace an SDL_ColorSpace value describing the surface + * \param colorspace an SDL_Colorspace value describing the surface * colorspace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace); /** * Get the colorspace used by a surface. @@ -243,7 +263,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surfa * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if * the surface is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorspace */ @@ -271,7 +291,7 @@ extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface * the surface didn't have an index format); call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors */ @@ -284,15 +304,15 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface * * * \param surface the SDL_Surface structure to update. * \param palette the SDL_Palette structure to use. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette); /** * Get the palette used by a surface. @@ -301,7 +321,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, * \returns a pointer to the palette used by the surface, or NULL if there is * no palette used. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfacePalette */ @@ -321,31 +341,30 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur * \param surface the SDL_Surface structure to update. * \param image a pointer to an alternate SDL_Surface to associate with this * surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages * \sa SDL_SurfaceHasAlternateImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); +extern SDL_DECLSPEC bool SDLCALL SDL_AddSurfaceAlternateImage(SDL_Surface *surface, SDL_Surface *image); /** * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if alternate versions are available or SDL_TRUE - * otherwise. + * \returns true if alternate versions are available or false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surface); /** * Get an array including all versions of a surface. @@ -364,7 +383,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface * * failure; call SDL_GetError() for more information. This should be * freed with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -380,7 +399,7 @@ extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *sur * * \param surface the SDL_Surface structure to update. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_GetSurfaceImages @@ -401,22 +420,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s * format of the surface will not change. * * \param surface the SDL_Surface structure to be locked. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_LockSurface(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_LockSurface(SDL_Surface *surface); /** * Release a surface after directly accessing the pixels. * * \param surface the SDL_Surface structure to be unlocked. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSurface */ @@ -429,18 +448,18 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); * will result in a memory leak. * * \param src the data stream for the surface. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning, - * even in the case of an error. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_bool closeio); +extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, bool closeio); /** * Load a BMP image from a file. @@ -452,7 +471,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_ * \returns a pointer to a new SDL_Surface structure or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP_IO @@ -471,17 +490,17 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file); * * \param surface the SDL_Surface structure containing the image to be saved. * \param dst a data stream to save to. - * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `dst` before returning, - * even in the case of an error. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closeio if true, calls SDL_CloseIO() on `dst` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, SDL_bool closeio); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStream *dst, bool closeio); /** * Save a surface to a file. @@ -494,15 +513,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IO * * \param surface the SDL_Surface structure containing the image to be saved. * \param file a file to save to. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); +extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); /** * Set the RLE acceleration hint for a surface. @@ -511,32 +530,31 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SaveBMP(SDL_Surface *surface, const cha * the surface must be locked before directly accessing the pixels. * * \param surface the SDL_Surface structure to optimize. - * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable - * it. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param enabled true to enable RLE acceleration, false to disable it. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface * \sa SDL_LockSurface * \sa SDL_UnlockSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, bool enabled); /** * Returns whether the surface is RLE enabled. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise. + * \returns true if the surface is RLE enabled, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceRLE */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); /** * Set the color key (transparent pixel) in a surface. @@ -549,34 +567,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); * SDL_MapRGB(). * * \param surface the SDL_Surface structure to update. - * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color - * key. + * \param enabled true to enable color key, false to disable color key. * \param key the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorKey * \sa SDL_SetSurfaceRLE * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, bool enabled, Uint32 key); /** * Returns whether the surface has a color key. * - * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. + * It is safe to pass a NULL `surface` here; it will return false. * * \param surface the SDL_Surface structure to query. - * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. + * \returns true if the surface has a color key, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); +extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface); /** * Get the color key (transparent pixel) for a surface. @@ -584,19 +601,19 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface * The color key is a pixel of the format used by the surface, as generated by * SDL_MapRGB(). * - * If the surface doesn't have color key enabled this function returns -1. + * If the surface doesn't have color key enabled this function returns false. * * \param surface the SDL_Surface structure to query. * \param key a pointer filled in with the transparent pixel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key); /** * Set an additional color value multiplied into blit operations. @@ -611,15 +628,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface * \param r the red color value multiplied into blit operations. * \param g the green color value multiplied into blit operations. * \param b the blue color value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b); /** @@ -629,15 +646,15 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface * \param r a pointer filled in with the current red color value. * \param g a pointer filled in with the current green color value. * \param b a pointer filled in with the current blue color value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b); /** * Set an additional alpha value used in blit operations. @@ -649,30 +666,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param alpha the alpha value multiplied into blit operations. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha); /** * Get the additional alpha value used in blit operations. * * \param surface the SDL_Surface structure to query. * \param alpha a pointer filled in with the current alpha value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha); /** * Set the blend mode used for blit operations. @@ -683,28 +700,28 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface * * \param surface the SDL_Surface structure to update. * \param blendMode the SDL_BlendMode to use for blit blending. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode); /** * Get the blend mode used for blit operations. * * \param surface the SDL_Surface structure to query. * \param blendMode a pointer filled in with the current SDL_BlendMode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceBlendMode */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode); /** * Set the clipping rectangle for a surface. @@ -718,14 +735,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surfac * \param surface the SDL_Surface structure to be clipped. * \param rect the SDL_Rect structure representing the clipping rectangle, or * NULL to disable clipping. - * \returns SDL_TRUE if the rectangle intersects the surface, otherwise - * SDL_FALSE and blits will be completely clipped. + * \returns true if the rectangle intersects the surface, otherwise false and + * blits will be completely clipped. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect); /** * Get the clipping rectangle for a surface. @@ -737,26 +754,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface * clipped. * \param rect an SDL_Rect structure filled in with the clipping rectangle for * the surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceClipRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect); /** * Flip a surface vertically or horizontally. * * \param surface the surface to flip. * \param flip the direction to flip. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); +extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip); /** * Creates a new surface identical to the existing surface. @@ -770,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_F * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -789,7 +806,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surf * \returns a copy of the surface or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface */ @@ -814,7 +831,7 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface, * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurfaceAndColorspace * \sa SDL_DestroySurface @@ -840,10 +857,9 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac * \returns the new SDL_Surface structure that is created or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurface - * \sa SDL_ConvertSurface * \sa SDL_DestroySurface */ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props); @@ -859,14 +875,14 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Su * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixelsAndColorspace */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch); /** * Copy a block of pixels of one format and colorspace to another format and @@ -875,27 +891,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixels(int width, int height, SD * \param width the width of the block to copy, in pixels. * \param height the height of the block to copy, in pixels. * \param src_format an SDL_PixelFormat value of the `src` pixels format. - * \param src_colorspace an SDL_ColorSpace value describing the colorspace of + * \param src_colorspace an SDL_Colorspace value describing the colorspace of * the `src` pixels. * \param src_properties an SDL_PropertiesID with additional source color * properties, or 0. * \param src a pointer to the source pixels. * \param src_pitch the pitch of the source pixels, in bytes. * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. - * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of * the `dst` pixels. * \param dst_properties an SDL_PropertiesID with additional destination color * properties, or 0. * \param dst a pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns SDL_FALSE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixels */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); +extern SDL_DECLSPEC bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch); /** * Premultiply the alpha on a block of pixels. @@ -910,14 +926,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ConvertPixelsAndColorspace(int width, i * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a pointer to be filled in with premultiplied pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch, bool linear); /** * Premultiply the alpha in a surface. @@ -925,14 +941,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplyAlpha(int width, int height, * This is safe to use with src == dst, but not for other overlapping areas. * * \param surface the surface to modify. - * \param linear SDL_TRUE to convert from sRGB to linear space for the alpha - * multiplication, SDL_FALSE to do multiplication in sRGB space. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param linear true to convert from sRGB to linear space for the alpha + * multiplication, false to do multiplication in sRGB space. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, SDL_bool linear); +extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surface, bool linear); /** * Clear a surface with a specific color, with floating point precision. @@ -947,12 +963,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *su * \param g the green component of the pixel, normally in the range 0-1. * \param b the blue component of the pixel, normally in the range 0-1. * \param a the alpha component of the pixel, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r, float g, float b, float a); /** * Perform a fast fill of a rectangle with a specific color. @@ -970,14 +986,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, floa * \param rect the SDL_Rect structure representing the rectangle to fill, or * NULL to fill the entire surface. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color); /** * Perform a fast fill of a set of rectangles with a specific color. @@ -995,22 +1011,24 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const * \param rects an array of SDL_Rects representing the rectangles to fill. * \param count the number of rectangles in the array. * \param color the color to fill with. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRect */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); +extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color); /** - * Performs a fast blit from the source surface to the destination surface. + * Performs a fast blit from the source surface to the destination surface + * with clipping. * - * This assumes that the source and destination rectangles are the same size. * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or - * `dst`) is copied. The final blit rectangles are saved in `srcrect` and - * `dstrect` after all clipping is performed. + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. + * + * The final blit rectangles are saved in `srcrect` and `dstrect` after all + * clipping is performed. * * The blit function should not be called on a locked surface. * @@ -1066,18 +1084,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, cons * height are ignored, and are copied from `srcrect`. If you * want a specific width and height, you should use * SDL_BlitSurfaceScaled(). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform low-level surface blitting only. @@ -1091,18 +1109,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit to a destination surface, which may be of a different @@ -1116,18 +1134,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUnchecked(SDL_Surface *src, * the destination surface, or NULL to fill the entire * destination surface. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform low-level surface scaled blitting only. @@ -1142,18 +1160,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, con * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, may not be NULL. * \param scaleMode the SDL_ScaleMode to be used. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode); /** * Perform a tiled blit to a destination surface, which may be of a different @@ -1168,18 +1186,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled and tiled blit to a destination surface, which may be of a @@ -1198,18 +1216,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiled(SDL_Surface *src, cons * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface *src, const SDL_Rect *srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Perform a scaled blit using the 9-grid algorithm to a destination surface, @@ -1235,18 +1253,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurfaceTiledWithScale(SDL_Surface * * \param dst the SDL_Surface structure that is the blit target. * \param dstrect the SDL_Rect structure representing the target rectangle in * the destination surface, or NULL to fill the entire surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety The same destination surface should not be used from two * threads at once. It is safe to use the same source surface * from multiple threads. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); +extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SDL_Rect *srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface *dst, const SDL_Rect *dstrect); /** * Map an RGB triple to an opaque pixel value for a surface. @@ -1272,7 +1290,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, cons * \param b the blue component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGBA */ @@ -1303,7 +1321,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 * \param a the alpha component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGB */ @@ -1329,12 +1347,12 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint * ignore this channel. * \param a a pointer filled in with the alpha channel, 0-255, or NULL to * ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a); /** * Retrieves a single pixel from a surface. @@ -1353,12 +1371,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, * 0-1, or NULL to ignore this channel. * \param a a pointer filled in with the alpha channel, normally in the range * 0-1, or NULL to ignore this channel. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); +extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface, int x, int y, float *r, float *g, float *b, float *a); /** * Writes a single pixel to a surface. @@ -1376,12 +1394,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surf * \param g the green channel value, 0-255. * \param b the blue channel value, 0-255. * \param a the alpha channel value, 0-255. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); /** * Writes a single pixel to a surface. @@ -1396,12 +1414,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, * \param g the green channel value, normally in the range 0-1. * \param b the blue channel value, normally in the range 0-1. * \param a the alpha channel value, normally in the range 0-1. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); +extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixelFloat(SDL_Surface *surface, int x, int y, float r, float g, float b, float a); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h index 17ac0a1..294089f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_system.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,13 @@ /** * # CategorySystem * - * Platform-specific SDL API functions. + * Platform-specific SDL API functions. These are functions that deal with + * needs of specific operating systems, that didn't make sense to offer as + * platform-independent, generic APIs. + * + * Most apps can make do without these functions, but they can be useful for + * integrating with other parts of a specific system, adding platform-specific + * polish to an app, or solving problems that only affect one target. */ #ifndef SDL_system_h_ @@ -31,7 +37,6 @@ #include #include #include -#include #include #include @@ -44,16 +49,15 @@ extern "C" { /* * Platform specific functions for Windows */ -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) +#if defined(SDL_PLATFORM_WINDOWS) typedef struct tagMSG MSG; /** * A callback to be used with SDL_SetWindowsMessageHook. * - * This callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * This callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * As this is processing a message directly from the Windows event loop, this * callback should do the minimum required work and return quickly. @@ -61,36 +65,35 @@ typedef struct tagMSG MSG; * \param userdata the app-defined pointer provided to * SDL_SetWindowsMessageHook. * \param msg a pointer to a Win32 event structure to process. - * \returns SDL_TRUE to let event continue on, SDL_FALSE to drop it. + * \returns true to let event continue on, false to drop it. * * \threadsafety This may only be called (by SDL) from the thread handling the * Windows event loop. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetWindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ -typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); +typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg); /** * Set a callback for every Windows message, run before TranslateMessage(). * - * The callback may modify the message, and should return SDL_TRUE if the - * message should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the message, and should return true if the message + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_WindowsMessageHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WindowsMessageHook * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP */ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK) */ +#endif /* defined(SDL_PLATFORM_WINDOWS) */ #if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) @@ -104,14 +107,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHoo * \returns the D3D9 adapter index on success or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID); -#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ - -#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) - /** * Get the DXGI Adapter and Output indices for the specified display. * @@ -122,33 +121,55 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displ * \param displayID the instance of the display to query. * \param adapterIndex a pointer to be filled in with the adapter index. * \param outputIndex a pointer to be filled in with the output index. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex); #endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */ + /* * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _XEvent XEvent; -typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); + +/** + * A callback to be used with SDL_SetX11EventHook. + * + * This callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * As this is processing an event directly from the X11 event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to SDL_SetX11EventHook. + * \param xevent a pointer to an Xlib XEvent union to process. + * \returns true to let event continue on, false to drop it. + * + * \threadsafety This may only be called (by SDL) from the thread handling the + * X11 event loop. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetX11EventHook + */ +typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** * Set a callback for every X11 event. * - * The callback may modify the event, and should return SDL_TRUE if the event - * should continue to be processed, or SDL_FALSE to prevent further - * processing. + * The callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. * * \param callback the SDL_X11EventHook function to call. * \param userdata a pointer to pass to every iteration of `callback`. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); @@ -162,12 +183,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, * * \param threadID the Unix thread ID to change priority of. * \param priority the new, Unix-specific, priority value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority); /** * Sets the priority (not nice level) and scheduling policy for a thread. @@ -178,12 +199,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, * \param sdlPriority the new SDL_ThreadPriority value. * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR, * SCHED_OTHER, etc...). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); +extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy); #endif /* SDL_PLATFORM_LINUX */ @@ -204,7 +225,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 * \param userdata what was passed as `callbackParam` to * SDL_SetiOSAnimationCallback as `callbackParam`. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ @@ -240,27 +261,27 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata); * called. * \param callback the function to call for every frame. * \param callbackParam a pointer that is passed to `callback`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSEventPump */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); +extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam); /** * Use this function to enable or disable the SDL event pump on Apple iOS. * * This function is only available on Apple iOS. * - * \param enabled SDL_TRUE to enable the event pump, SDL_FALSE to disable it. + * \param enabled true to enable the event pump, false to disable it. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetiOSAnimationCallback */ -extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); +extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled); #endif /* SDL_PLATFORM_IOS */ @@ -286,7 +307,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidActivity */ @@ -311,7 +332,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidJNIEnv */ @@ -349,43 +370,34 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); * * \returns the Android API level. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); -/** - * Query if the application is running on Android TV. - * - * \returns SDL_TRUE if this is Android TV, SDL_FALSE otherwise. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsAndroidTV(void); - /** * Query if the application is running on a Chromebook. * - * \returns SDL_TRUE if this is a Chromebook, SDL_FALSE otherwise. + * \returns true if this is a Chromebook, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsChromebook(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); /** * Query if the application is running on a Samsung DeX docking station. * - * \returns SDL_TRUE if this is a DeX docking station, SDL_FALSE otherwise. + * \returns true if this is a DeX docking station, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void); /** * Trigger the Android system back button behavior. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); @@ -393,9 +405,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * See the official Android developer guide for more information: * http://developer.android.com/guide/topics/data/data-storage.html * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 + +/** + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -414,9 +433,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \returns the path used for internal storage or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * - * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidExternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void); @@ -431,7 +451,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void) * \returns the current state of external storage, or 0 if external storage is * currently unavailable. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStoragePath */ @@ -453,9 +473,11 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); * \returns the path used for external storage for this application on success * or NULL on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAndroidExternalStorageState + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidCachePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void); @@ -474,12 +496,25 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) * \returns the path used for caches for this application on success or NULL * on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAndroidInternalStoragePath + * \sa SDL_GetAndroidExternalStoragePath */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - -typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted); +/** + * Callback that presents a response from a SDL_RequestAndroidPermission call. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param permission the Android-specific permission name that was requested. + * \param granted true if permission is granted, false if denied. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RequestAndroidPermission + */ +typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** * Request permissions at runtime, asynchronously. @@ -500,18 +535,22 @@ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, con * like memory running out. Normally there will be a yes or no to the request * through the callback. * + * For the `permission` parameter, choose a value from here: + * + * https://developer.android.com/reference/android/Manifest.permission + * * \param permission the permission to request. * \param cb the callback to trigger when the request has a response. * \param userdata an app-controlled pointer that is passed to the callback. - * \returns SDL_TRUE if the request was submitted, SDL_FALSE if there was an - * error submitting. The result of the request is only ever reported + * \returns true if the request was submitted, false if there was an error + * submitting. The result of the request is only ever reported * through the callback, not this return value. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); +extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata); /** * Shows an Android toast notification. @@ -532,14 +571,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RequestAndroidPermission(const char *pe * \param gravity where the notification should appear on the screen. * \param xoffset set this parameter only when gravity >=0. * \param yoffset set this parameter only when gravity >=0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset); /** * Send a user command to SDLActivity. @@ -548,111 +587,63 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowAndroidToast(const char *message, i * * \param command user command that must be greater or equal to 0x8000. * \param param user parameter. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); +extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param); #endif /* SDL_PLATFORM_ANDROID */ -/* - * Platform specific functions for WinRT - */ -#ifdef SDL_PLATFORM_WINRT - -/** - * WinRT / Windows Phone path types - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_Path -{ - /** The installed app's root directory. - Files here are likely to be read-only. */ - SDL_WINRT_PATH_INSTALLED_LOCATION, - - /** The app's local data store. Files may be written here */ - SDL_WINRT_PATH_LOCAL_FOLDER, - - /** The app's roaming data store. Unsupported on Windows Phone. - Files written here may be copied to other machines via a network - connection. - */ - SDL_WINRT_PATH_ROAMING_FOLDER, - - /** The app's temporary data store. Unsupported on Windows Phone. - Files written here may be deleted at any time. */ - SDL_WINRT_PATH_TEMP_FOLDER -} SDL_WinRT_Path; - - -/** - * WinRT Device Family - * - * \since This enum is available since SDL 3.0.0. - */ -typedef enum SDL_WinRT_DeviceFamily -{ - /** Unknown family */ - SDL_WINRT_DEVICEFAMILY_UNKNOWN, - - /** Desktop family*/ - SDL_WINRT_DEVICEFAMILY_DESKTOP, - - /** Mobile family (for example smartphone) */ - SDL_WINRT_DEVICEFAMILY_MOBILE, - - /** XBox family */ - SDL_WINRT_DEVICEFAMILY_XBOX, -} SDL_WinRT_DeviceFamily; - - -/** - * Retrieve a WinRT defined path on the local file system. - * - * Not all paths are available on all versions of Windows. This is especially - * true on Windows Phone. Check the documentation for the given SDL_WinRT_Path - * for more information on which path types are supported where. - * - * Documentation on most app-specific path types on WinRT can be found on - * MSDN, at the URL: - * - * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx - * - * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. - * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if - * the path is not available for any reason; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType); - -/** - * Detects the device family of WinRT platform at runtime. - * - * \returns a value from the SDL_WinRT_DeviceFamily enum. - * - * \since This function is available since SDL 3.0.0. - */ -extern SDL_DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_GetWinRTDeviceFamily(); - -#endif /* SDL_PLATFORM_WINRT */ - /** * Query if the current device is a tablet. * - * If SDL can't determine this, it will return SDL_FALSE. + * If SDL can't determine this, it will return false. * - * \returns SDL_TRUE if the device is a tablet, SDL_FALSE otherwise. + * \returns true if the device is a tablet, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); +extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); + +/** + * Query if the current device is a TV. + * + * If SDL can't determine this, it will return false. + * + * \returns true if the device is a TV, false otherwise. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void); + +/** + * Application sandbox environment. + * + * \since This enum is available since SDL 3.2.0. + */ +typedef enum SDL_Sandbox +{ + SDL_SANDBOX_NONE = 0, + SDL_SANDBOX_UNKNOWN_CONTAINER, + SDL_SANDBOX_FLATPAK, + SDL_SANDBOX_SNAP, + SDL_SANDBOX_MACOS +} SDL_Sandbox; + +/** + * Get the application sandbox environment, if any. + * + * \returns the application sandbox environment or SDL_SANDBOX_NONE if the + * application is not running in a sandbox environment. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void); + /* Functions used by iOS app delegates to notify SDL about state changes. */ @@ -669,7 +660,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsTablet(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); @@ -686,7 +677,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); @@ -703,7 +694,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); @@ -720,7 +711,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); @@ -737,7 +728,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); @@ -754,7 +745,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); @@ -773,7 +764,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void); #endif @@ -794,12 +785,12 @@ typedef struct XUser *XUserHandle; * leak. * * \param outTaskQueue a pointer to be filled in with task queue handle. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue); /** * Gets a reference to the default user handle for GDK. @@ -809,12 +800,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTa * * \param outUserHandle a pointer to be filled in with the default user * handle. - * \returns SDL_TRUE if success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true if success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); +extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle); #endif diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h index 0fdc8a0..277535f 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_thread.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,19 @@ /** * # CategoryThread * - * SDL thread management routines. + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. */ #include @@ -34,9 +46,8 @@ /* Thread synchronization primitives */ #include -#include -#if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +#if defined(SDL_PLATFORM_WINDOWS) #include /* _beginthreadex() and _endthreadex() */ #endif @@ -51,7 +62,7 @@ extern "C" { * * These are opaque data. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -65,7 +76,7 @@ typedef struct SDL_Thread SDL_Thread; * application will operate on, but having a way to uniquely identify a thread * can be useful at times. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetThreadID * \sa SDL_GetCurrentThreadID @@ -78,7 +89,7 @@ typedef Uint64 SDL_ThreadID; * 0 is the invalid ID. An app can create these and then set data for these * IDs that is unique to each thread. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetTLS * \sa SDL_SetTLS @@ -90,11 +101,11 @@ typedef SDL_AtomicInt SDL_TLSID; * * SDL will make system changes as necessary in order to apply the thread * priority. Code which attempts to control thread state related to priority - * should be aware that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this - * behavior. + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, @@ -103,13 +114,30 @@ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_TIME_CRITICAL } SDL_ThreadPriority; +/** + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + */ +typedef enum SDL_ThreadState +{ + SDL_THREAD_UNKNOWN, /**< The thread is not valid */ + SDL_THREAD_ALIVE, /**< The thread is currently running */ + SDL_THREAD_DETACHED, /**< The thread is detached and can't be waited on */ + SDL_THREAD_COMPLETE /**< The thread has finished and should be cleaned up with SDL_WaitThread() */ +} SDL_ThreadState; + /** * The function passed to SDL_CreateThread() as the new thread's entry point. * * \param data what was passed as `data` to SDL_CreateThread(). * \returns a value that can be reported through SDL_WaitThread(). * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -179,7 +207,7 @@ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThreadWithProperties * \sa SDL_WaitThread @@ -245,7 +273,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -263,7 +291,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop /* The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. */ #ifndef SDL_WIKI_DOCUMENTATION_SECTION -# if (defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_GDK)) && !defined(SDL_PLATFORM_WINRT) +# if defined(SDL_PLATFORM_WINDOWS) # ifndef SDL_BeginThreadFunction # define SDL_BeginThreadFunction _beginthreadex # endif @@ -300,7 +328,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -314,7 +342,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunct * new thread could not be created; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -334,7 +362,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S * \returns a pointer to a UTF-8 string that names the specified thread, or * NULL if it doesn't have a name. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); @@ -350,7 +378,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); * * \returns the ID of the current thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetThreadID */ @@ -367,7 +395,7 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentThreadID */ @@ -381,25 +409,25 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * an administrator account. Be prepared for this to fail. * * \param priority the SDL_ThreadPriority to set. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); +extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority priority); /** * Wait for a thread to finish. * - * Threads that haven't been detached will remain (as a "zombie") until this - * function cleans them up. Not doing so is a resource leak. + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. * * Once a thread has been cleaned up through this function, the SDL_Thread * that references it becomes invalid and should not be referenced again. As * such, only one thread may call SDL_WaitThread() on another. * - * The return code for the thread function is placed in the area pointed to by - * `status`, if `status` is not NULL. + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not NULL. * * You may not wait on a thread that has been used in a call to * SDL_DetachThread(). Use either that function or this one, but not both, or @@ -412,17 +440,30 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority pr * * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. - * \param status pointer to an integer that will receive the value returned - * from the thread function by its 'return', or NULL to not - * receive such value back. + * \param status a pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_DetachThread */ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status); +/** + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + */ +extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *thread); + /** * Let a thread clean up on exit without intervention. * @@ -452,7 +493,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status) * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread * \sa SDL_WaitThread @@ -468,7 +509,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread *thread); * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -481,7 +522,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetTLS(SDL_TLSID *id); * * \param value a pointer previously handed to SDL_SetTLS. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_SetTLS */ @@ -504,16 +545,16 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void *value); * \param value the value to associate with the ID for the current thread. * \param destructor a function called when the thread exits, to free the * value, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetTLS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); +extern SDL_DECLSPEC bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor); /** * Cleanup all TLS data for this thread. @@ -524,7 +565,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_CleanupTLS(void); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h index 86c1fad..b6d3f6d 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_time.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -26,6 +26,14 @@ freely, subject to the following restrictions: * # CategoryTime * * SDL realtime clock and date/time routines. + * + * There are two data types that are used in this category: SDL_Time, which + * represents the nanoseconds since a specific moment (an "epoch"), and + * SDL_DateTime, which breaks time down into human-understandable components: + * years, months, days, hours, etc. + * + * Much of the functionality is involved in converting those two types to + * other useful forms. */ #include @@ -41,7 +49,7 @@ extern "C" { * A structure holding a calendar date and time broken down into its * components. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. */ typedef struct SDL_DateTime { @@ -59,7 +67,7 @@ typedef struct SDL_DateTime /** * The preferred date format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -73,7 +81,7 @@ typedef enum SDL_DateFormat /** * The preferred time format of the current system locale. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_GetDateTimeLocalePreferences */ @@ -95,24 +103,24 @@ typedef enum SDL_TimeFormat * format, may be NULL. * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time * format, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); /** * Gets the current value of the system realtime clock in nanoseconds since * Jan 1, 1970 in Universal Coordinated Time (UTC). * * \param ticks the SDL_Time to hold the returned tick count. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); /** * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in @@ -123,12 +131,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \param localTime the resulting SDL_DateTime will be expressed in local time * if true, otherwise it will be in Universal Coordinated * Time (UTC). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, SDL_bool localTime); +extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); /** * Converts a calendar time to an SDL_Time in nanoseconds since the epoch. @@ -138,12 +146,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_Date * * \param dt the source SDL_DateTime. * \param ticks the resulting SDL_Time. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); +extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); /** * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals @@ -157,7 +165,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, * \param dwHighDateTime a pointer filled in with the high portion of the * Windows FILETIME value. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); @@ -172,7 +180,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow * \param dwHighDateTime the high portion of the Windows FILETIME value. * \returns the converted SDL time. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); @@ -184,7 +192,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * \returns the number of days in the requested month or -1 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); @@ -197,7 +205,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \returns the day of year [0-365] if the date is valid or -1 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); @@ -210,7 +218,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or * -1 on failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h index 9d05161..cf94881 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_timer.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -25,7 +25,20 @@ /** * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. */ #include @@ -38,16 +51,137 @@ extern "C" { #endif /* SDL time constants */ + +/** + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_PER_SECOND 1000 + +/** + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_PER_SECOND 1000000 + +/** + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_SECOND 1000000000LL + +/** + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_MS 1000000 + +/** + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_PER_US 1000 + +/** + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_SECONDS_TO_NS(S) (((Uint64)(S)) * SDL_NS_PER_SECOND) + +/** + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_SECONDS(NS) ((NS) / SDL_NS_PER_SECOND) + +/** + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MS_TO_NS(MS) (((Uint64)(MS)) * SDL_NS_PER_MS) + +/** + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_MS(NS) ((NS) / SDL_NS_PER_MS) + +/** + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_US_TO_NS(US) (((Uint64)(US)) * SDL_NS_PER_US) + +/** + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_NS_TO_US(NS) ((NS) / SDL_NS_PER_US) /** @@ -56,7 +190,9 @@ extern "C" { * \returns an unsigned 64-bit value representing the number of milliseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); @@ -66,7 +202,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); * \returns an unsigned 64-bit value representing the number of nanoseconds * since the SDL library initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); @@ -81,7 +219,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); * * \returns the current counter value. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceFrequency */ @@ -92,7 +232,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); * * \returns a platform-specific count per second. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceCounter */ @@ -107,10 +249,33 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * * \param ms the number of milliseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); +/** + * Wait a specified number of nanoseconds before returning. + * + * This function waits a specified number of nanoseconds before returning. It + * waits at least the specified time, but possibly longer due to OS + * scheduling. + * + * \param ns the number of nanoseconds to delay. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise + */ +extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); + /** * Wait a specified number of nanoseconds before returning. * @@ -120,14 +285,19 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * * \param ns the number of nanoseconds to delay. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS */ -extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); +extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); /** * Definition of the timer ID type. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_TimerID; @@ -151,7 +321,7 @@ typedef Uint32 SDL_TimerID; * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimer */ @@ -160,8 +330,6 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimer() call and should return the next * timer interval. If the value returned from the callback is 0, the timer is @@ -188,7 +356,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimerNS * \sa SDL_RemoveTimer @@ -215,7 +383,7 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, SDL_TimerC * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimerNS */ @@ -224,8 +392,6 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI /** * Call a callback function at a future time. * - * If you use this function, you must pass `SDL_INIT_TIMER` to SDL_Init(). - * * The callback function is passed the current timer interval and the user * supplied parameter from the SDL_AddTimerNS() call and should return the * next timer interval. If the value returned from the callback is 0, the @@ -252,7 +418,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer * \sa SDL_RemoveTimer @@ -263,14 +429,16 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * Remove a timer created with SDL_AddTimer(). * * \param id the ID of the timer to remove. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); +extern SDL_DECLSPEC bool SDLCALL SDL_RemoveTimer(SDL_TimerID id); /* Ends C function definitions when using C++ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h index 6889f36..64845a1 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_touch.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,18 @@ /** * # CategoryTouch * - * SDL touch management. + * SDL offers touch input, on platforms that support it. It can manage + * multiple touch devices and track multiple fingers on those devices. + * + * Touches are mostly dealt with through the event system, in the + * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP + * events, but there are also functions to query for hardware details, etc. + * + * The touch system, by default, will also send virtual mouse events; this can + * be useful for making a some desktop apps work on a phone without + * significant changes. For apps that care about mouse and touch input + * separately, they should ignore mouse events that have a `which` field of + * SDL_TOUCH_MOUSEID. */ #ifndef SDL_touch_h_ @@ -31,7 +42,6 @@ #include #include #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -39,25 +49,53 @@ extern "C" { #endif +/** + * A unique ID for a touch device. + * + * This ID is valid for the time the device is connected to the system, and is + * never reused for the lifetime of the application. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_TouchID; + +/** + * A unique ID for a single finger on a touch device. + * + * This ID is valid for the time the finger (stylus, etc) is touching and will + * be unique for all fingers currently in contact, so this ID tracks the + * lifetime of a single continuous touch. This value may represent an index, a + * pointer, or some other unique ID, depending on the platform. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef Uint64 SDL_FingerID; +/** + * An enum that describes the type of a touch device. + * + * \since This enum is available since SDL 3.2.0. + */ typedef enum SDL_TouchDeviceType { SDL_TOUCH_DEVICE_INVALID = -1, - SDL_TOUCH_DEVICE_DIRECT, /* touch screen with window-relative coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /* trackpad with absolute device coordinates */ - SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ + SDL_TOUCH_DEVICE_DIRECT, /**< touch screen with window-relative coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE, /**< trackpad with absolute device coordinates */ + SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /**< trackpad with screen cursor-relative coordinates */ } SDL_TouchDeviceType; /** * Data about a single finger in a multitouch event. * - * Each touch even is a collection of fingers that are simultaneously in + * Each touch event is a collection of fingers that are simultaneously in * contact with the touch device (so a "touch" can be a "multitouch," in * reality), and this struct reports details of the specific fingers. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetTouchFingers */ @@ -69,10 +107,18 @@ typedef struct SDL_Finger float pressure; /**< the quantity of pressure applied, normalized (0...1) */ } SDL_Finger; -/* Used as the device ID for mouse events simulated with touch input */ +/** + * The SDL_MouseID for mouse events simulated with touch input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) -/* Used as the SDL_TouchID for touch events simulated with mouse input */ +/** + * The SDL_TouchID for touch events simulated with mouse input. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) @@ -89,7 +135,7 @@ typedef struct SDL_Finger * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); @@ -100,7 +146,7 @@ extern SDL_DECLSPEC SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); * \returns touch device name, or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID); @@ -110,7 +156,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touc * \param touchID the ID of a touch device. * \returns touch device type. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID touchID); @@ -125,7 +171,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Finger ** SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_tray.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_tray.h new file mode 100644 index 0000000..0b05db2 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_tray.h @@ -0,0 +1,544 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2025 Sam Lantinga + + 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. +*/ + +/** + * # CategoryTray + * + * SDL offers a way to add items to the "system tray" (more correctly called + * the "notification area" on Windows). On platforms that offer this concept, + * an SDL app can add a tray icon, submenus, checkboxes, and clickable + * entries, and register a callback that is fired when the user clicks on + * these pieces. + */ + +#ifndef SDL_tray_h_ +#define SDL_tray_h_ + +#include +#include +#include +#include + +#include +/* Set up for C function definitions, even when using C++ */ +#ifdef __cplusplus +extern "C" { +#endif + +/** + * An opaque handle representing a toplevel system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_Tray SDL_Tray; + +/** + * An opaque handle representing a menu/submenu on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayMenu SDL_TrayMenu; + +/** + * An opaque handle representing an entry on a system tray object. + * + * \since This struct is available since SDL 3.2.0. + */ +typedef struct SDL_TrayEntry SDL_TrayEntry; + +/** + * Flags that control the creation of system tray entries. + * + * Some of these flags are required; exactly one of them must be specified at + * the time a tray entry is created. Other flags are optional; zero or more of + * those can be OR'ed together with the required flag. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +typedef Uint32 SDL_TrayEntryFlags; + +#define SDL_TRAYENTRY_BUTTON 0x00000001u /**< Make the entry a simple button. Required. */ +#define SDL_TRAYENTRY_CHECKBOX 0x00000002u /**< Make the entry a checkbox. Required. */ +#define SDL_TRAYENTRY_SUBMENU 0x00000004u /**< Prepare the entry to have a submenu. Required */ +#define SDL_TRAYENTRY_DISABLED 0x80000000u /**< Make the entry disabled. Optional. */ +#define SDL_TRAYENTRY_CHECKED 0x40000000u /**< Make the entry checked. This is valid only for checkboxes. Optional. */ + +/** + * A callback that is invoked when a tray entry is selected. + * + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * \param entry the tray entry that was selected. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTrayEntryCallback + */ +typedef void (SDLCALL *SDL_TrayCallback)(void *userdata, SDL_TrayEntry *entry); + +/** + * Create an icon to be placed in the operating system's tray, or equivalent. + * + * Many platforms advise not using a system tray unless persistence is a + * necessary feature. Avoid needlessly creating a tray icon, as the user may + * feel like it clutters their interface. + * + * Using tray icons require the video subsystem. + * + * \param icon a surface to be used as icon. May be NULL. + * \param tooltip a tooltip to be displayed when the mouse hovers the icon in + * UTF-8 encoding. Not supported on all platforms. May be NULL. + * \returns The newly created system tray icon. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenu + * \sa SDL_DestroyTray + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_CreateTray(SDL_Surface *icon, const char *tooltip); + +/** + * Updates the system tray icon's icon. + * + * \param tray the tray icon to be updated. + * \param icon the new icon. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayIcon(SDL_Tray *tray, SDL_Surface *icon); + +/** + * Updates the system tray icon's tooltip. + * + * \param tray the tray icon to be updated. + * \param tooltip the new tooltip in UTF-8 encoding. May be NULL. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayTooltip(SDL_Tray *tray, const char *tooltip); + +/** + * Create a menu for a system tray. + * + * This should be called at most once per tray icon. + * + * This function does the same thing as SDL_CreateTraySubmenu(), except that + * it takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_GetTrayMenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTrayMenu(SDL_Tray *tray); + +/** + * Create a submenu for a system tray entry. + * + * This should be called at most once per tray entry. + * + * This function does the same thing as SDL_CreateTrayMenu, except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTraySubmenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_CreateTraySubmenu(SDL_TrayEntry *entry); + +/** + * Gets a previously created tray menu. + * + * You should have called SDL_CreateTrayMenu() on the tray object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTraySubmenu(), except that it + * takes a SDL_Tray instead of a SDL_TrayEntry. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param tray the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + * \sa SDL_CreateTrayMenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayMenu(SDL_Tray *tray); + +/** + * Gets a previously created tray entry submenu. + * + * You should have called SDL_CreateTraySubmenu() on the entry object. This + * function allows you to fetch it again later. + * + * This function does the same thing as SDL_GetTrayMenu(), except that it + * takes a SDL_TrayEntry instead of a SDL_Tray. + * + * A menu does not need to be destroyed; it will be destroyed with the tray. + * + * \param entry the tray entry to bind the menu to. + * \returns the newly created menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + * \sa SDL_CreateTraySubmenu + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTraySubmenu(SDL_TrayEntry *entry); + +/** + * Returns a list of entries in the menu, in order. + * + * \param menu The menu to get entries from. + * \param size An optional pointer to obtain the number of entries in the + * menu. + * \returns a NULL-terminated list of entries within the given menu. The + * pointer becomes invalid when any function that inserts or deletes + * entries in the menu is called. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveTrayEntry + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC const SDL_TrayEntry **SDLCALL SDL_GetTrayEntries(SDL_TrayMenu *menu, int *size); + +/** + * Removes a tray entry. + * + * \param entry The entry to be deleted. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_RemoveTrayEntry(SDL_TrayEntry *entry); + +/** + * Insert a tray entry at a given position. + * + * If label is NULL, the entry will be a separator. Many functions won't work + * for an entry that is a separator. + * + * An entry does not need to be destroyed; it will be destroyed with the tray. + * + * \param menu the menu to append the entry to. + * \param pos the desired position for the new entry. Entries at or following + * this place will be moved. If pos is -1, the entry is appended. + * \param label the text to be displayed on the entry, in UTF-8 encoding, or + * NULL for a separator. + * \param flags a combination of flags, some of which are mandatory. + * \returns the newly created entry, or NULL if pos is out of bounds. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TrayEntryFlags + * \sa SDL_GetTrayEntries + * \sa SDL_RemoveTrayEntry + * \sa SDL_GetTrayEntryParent + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_InsertTrayEntryAt(SDL_TrayMenu *menu, int pos, const char *label, SDL_TrayEntryFlags flags); + +/** + * Sets the label of an entry. + * + * An entry cannot change between a separator and an ordinary entry; that is, + * it is not possible to set a non-NULL label on an entry that has a NULL + * label (separators), or to set a NULL label to an entry that has a non-NULL + * label. The function will silently fail if that happens. + * + * \param entry the entry to be updated. + * \param label the new label for the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryLabel + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryLabel(SDL_TrayEntry *entry, const char *label); + +/** + * Gets the label of an entry. + * + * If the returned value is NULL, the entry is a separator. + * + * \param entry the entry to be read. + * \returns the label of the entry in UTF-8 encoding. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryLabel + */ +extern SDL_DECLSPEC const char *SDLCALL SDL_GetTrayEntryLabel(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be updated. + * \param checked true if the entry should be checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryChecked + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryChecked(SDL_TrayEntry *entry, bool checked); + +/** + * Gets whether or not an entry is checked. + * + * The entry must have been created with the SDL_TRAYENTRY_CHECKBOX flag. + * + * \param entry the entry to be read. + * \returns true if the entry is checked; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryChecked + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryChecked(SDL_TrayEntry *entry); + +/** + * Sets whether or not an entry is enabled. + * + * \param entry the entry to be updated. + * \param enabled true if the entry should be enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_GetTrayEntryEnabled + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryEnabled(SDL_TrayEntry *entry, bool enabled); + +/** + * Gets whether or not an entry is enabled. + * + * \param entry the entry to be read. + * \returns true if the entry is enabled; false otherwise. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + * \sa SDL_SetTrayEntryEnabled + */ +extern SDL_DECLSPEC bool SDLCALL SDL_GetTrayEntryEnabled(SDL_TrayEntry *entry); + +/** + * Sets a callback to be invoked when the entry is selected. + * + * \param entry the entry to be updated. + * \param callback a callback to be invoked when the entry is selected. + * \param userdata an optional pointer to pass extra data to the callback when + * it will be invoked. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTrayEntries + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC void SDLCALL SDL_SetTrayEntryCallback(SDL_TrayEntry *entry, SDL_TrayCallback callback, void *userdata); + +/** + * Simulate a click on a tray entry. + * + * \param entry The entry to activate. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_ClickTrayEntry(SDL_TrayEntry *entry); + +/** + * Destroys a tray object. + * + * This also destroys all associated menus and entries. + * + * \param tray the tray icon to be destroyed. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTray + */ +extern SDL_DECLSPEC void SDLCALL SDL_DestroyTray(SDL_Tray *tray); + +/** + * Gets the menu containing a certain tray entry. + * + * \param entry the entry for which to get the parent menu. + * \returns the parent menu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InsertTrayEntryAt + */ +extern SDL_DECLSPEC SDL_TrayMenu *SDLCALL SDL_GetTrayEntryParent(SDL_TrayEntry *entry); + +/** + * Gets the entry for which the menu is a submenu, if the current menu is a + * submenu. + * + * Either this function or SDL_GetTrayMenuParentTray() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent entry. + * \returns the parent entry, or NULL if this menu is not a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTraySubmenu + * \sa SDL_GetTrayMenuParentTray + */ +extern SDL_DECLSPEC SDL_TrayEntry *SDLCALL SDL_GetTrayMenuParentEntry(SDL_TrayMenu *menu); + +/** + * Gets the tray for which this menu is the first-level menu, if the current + * menu isn't a submenu. + * + * Either this function or SDL_GetTrayMenuParentEntry() will return non-NULL + * for any given menu. + * + * \param menu the menu for which to get the parent enttrayry. + * \returns the parent tray, or NULL if this menu is a submenu. + * + * \threadsafety This function should be called on the thread that created the + * tray. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateTrayMenu + * \sa SDL_GetTrayMenuParentEntry + */ +extern SDL_DECLSPEC SDL_Tray *SDLCALL SDL_GetTrayMenuParentTray(SDL_TrayMenu *menu); + +/** + * Update the trays. + * + * This is called automatically by the event loop and is only needed if you're + * using trays but aren't handling SDL events. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + */ +extern SDL_DECLSPEC void SDLCALL SDL_UpdateTrays(void); + +/* Ends C function definitions when using C++ */ +#ifdef __cplusplus +} +#endif +#include + +#endif /* SDL_tray_h_ */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h index c0f518d..55014e3 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_version.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -30,7 +30,6 @@ #define SDL_version_h_ #include -#include #include /* Set up for C function definitions, even when using C++ */ @@ -43,7 +42,7 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 3. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_MAJOR_VERSION 3 @@ -52,18 +51,18 @@ extern "C" { * * If this were SDL version 3.2.1, this value would be 2. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MINOR_VERSION 1 +#define SDL_MINOR_VERSION 2 /** * The current micro (or patchlevel) version of the SDL headers. * * If this were SDL version 3.2.1, this value would be 1. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ -#define SDL_MICRO_VERSION 2 +#define SDL_MICRO_VERSION 0 /** * This macro turns the version numbers into a numeric value. @@ -74,7 +73,7 @@ extern "C" { * \param minor the minorversion number. * \param patch the patch version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM(major, minor, patch) \ ((major) * 1000000 + (minor) * 1000 + (patch)) @@ -86,7 +85,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) @@ -97,7 +96,7 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) @@ -108,14 +107,16 @@ extern "C" { * * \param version the version number. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) /** * This is the version number macro for the current SDL version. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetVersion */ #define SDL_VERSION \ SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_MICRO_VERSION) @@ -123,7 +124,7 @@ extern "C" { /** * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * - * \since This macro is available since SDL 3.0.0. + * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ (SDL_VERSION >= SDL_VERSIONNUM(X, Y, Z)) @@ -140,7 +141,7 @@ extern "C" { * * \returns the version of the linked library. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRevision */ @@ -166,7 +167,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); * \returns an arbitrary string, uniquely identifying the exact revision of * the SDL library in use. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVersion */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h index 7cce828..a7afc32 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_video.h @@ -1,6 +1,6 @@ /* Simple DirectMedia Layer - Copyright (C) 1997-2024 Sam Lantinga + Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -22,7 +22,28 @@ /** * # CategoryVideo * - * SDL video functions. + * SDL's video subsystem is largely interested in abstracting window + * management from the underlying operating system. You can create windows, + * manage them in various ways, set them fullscreen, and get events when + * interesting things happen with them, such as the mouse or keyboard + * interacting with a window. + * + * The video subsystem is also interested in abstracting away some + * platform-specific differences in OpenGL: context creation, swapping + * buffers, etc. This may be crucial to your app, but also you are not + * required to use OpenGL at all. In fact, SDL can provide rendering to those + * windows as well, either with an easy-to-use + * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender) + * or with a more-powerful + * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU) + * . Of course, it can simply get out of your way and give you the window + * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like + * directly, too. + * + * The video subsystem covers a lot of functionality, out of necessity, so it + * is worth perusing the list of functions just to see what's available, but + * most apps can get by with simply creating a window and listening for + * events, so start with SDL_CreateWindow() and SDL_PollEvent(). */ #ifndef SDL_video_h_ @@ -49,7 +70,7 @@ extern "C" { * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_DisplayID; @@ -58,7 +79,7 @@ typedef Uint32 SDL_DisplayID; * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef Uint32 SDL_WindowID; @@ -82,7 +103,7 @@ typedef Uint32 SDL_WindowID; /** * System theme. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_SystemTheme { @@ -91,13 +112,21 @@ typedef enum SDL_SystemTheme SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ } SDL_SystemTheme; -/* Internal display mode data */ +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** * The structure that defines a display mode. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetFullscreenDisplayModes * \sa SDL_GetDesktopDisplayMode @@ -123,7 +152,7 @@ typedef struct SDL_DisplayMode /** * Display orientation values; the way a display is rotated. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_DisplayOrientation { @@ -137,7 +166,7 @@ typedef enum SDL_DisplayOrientation /** * The struct used as an opaque handle to a window. * - * \since This struct is available since SDL 3.0.0. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateWindow */ @@ -151,7 +180,7 @@ typedef struct SDL_Window SDL_Window; * changed on existing windows by the app, and some of it might be altered by * the user or system outside of the app's control. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ @@ -185,31 +214,91 @@ typedef Uint64 SDL_WindowFlags; /** - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. * - * \since This macro is available since SDL 3.0.0. + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u + +/** + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) + +/** + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A magic value used with SDL_WINDOWPOS_CENTERED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. + */ +#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u /** * Used to indicate that the window position should be centered. * - * \since This macro is available since SDL 3.0.0. + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. */ -#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) + +/** + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ typedef enum SDL_FlashOperation { @@ -221,30 +310,102 @@ typedef enum SDL_FlashOperation /** * An opaque handle to an OpenGL context. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * - * \since This datatype is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + */ typedef int SDL_EGLint; /** - * EGL attribute initialization callback types. + * EGL platform attribute initialization callback. * - * \since This datatype is available since SDL 3.0.0. + * This is called when SDL is attempting to create an EGL context, to let the + * app add extra attributes to its eglGetPlatformDisplay() call. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks */ -typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); -typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); +typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata); + +/** + * EGL surface/context attribute initialization callback types. + * + * This is called when SDL is attempting to create an EGL surface, to let the + * app add extra attributes to its eglCreateWindowSurface() or + * eglCreateContext calls. + * + * For convenience, the EGLDisplay and EGLConfig to use are provided to the + * callback. + * + * The callback should return a pointer to an EGL attribute array terminated + * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow + * process will fail gracefully. + * + * The returned pointer should be allocated with SDL_malloc() and will be + * passed to SDL_free(). + * + * The arrays returned by each callback will be appended to the existing + * attribute arrays defined by SDL. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param display the EGL display to be used. + * \param config the EGL config to be used. + * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_EGL_SetAttributeCallbacks + */ +typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config); /** * An enumeration of OpenGL configuration attributes. @@ -261,9 +422,9 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); * fail if the GL can't provide your requested attributes at a minimum, but * you should check to see exactly what you got. * - * \since This enum is available since SDL 3.0.0. + * \since This enum is available since SDL 3.2.0. */ -typedef enum SDL_GLattr +typedef enum SDL_GLAttr { SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */ SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */ @@ -284,64 +445,64 @@ typedef enum SDL_GLattr SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */ SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */ SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */ - SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */ - SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */ + SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */ + SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */ SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */ SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. */ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLcontextReleaseFlag; defaults to FLUSH. */ + SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */ SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */ SDL_GL_CONTEXT_NO_ERROR, SDL_GL_FLOATBUFFERS, SDL_GL_EGL_PLATFORM -} SDL_GLattr; +} SDL_GLAttr; /** * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLprofile -{ - SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, - SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, - SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ -} SDL_GLprofile; +typedef Uint32 SDL_GLProfile; + +#define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */ +#define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */ +#define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ + /** - * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextFlag -{ - SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, - SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, - SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG = 0x0004, - SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 -} SDL_GLcontextFlag; +typedef Uint32 SDL_GLContextFlag; + +#define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001 +#define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002 +#define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004 +#define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008 + /** * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR * attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLcontextReleaseFlag -{ - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, - SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 -} SDL_GLcontextReleaseFlag; +typedef Uint32 SDL_GLContextReleaseFlag; + +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000 +#define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001 + /** * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. * - * \since This enum is available since SDL 3.0.0. + * \since This datatype is available since SDL 3.2.0. */ -typedef enum SDL_GLContextResetNotification -{ - SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, - SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 -} SDL_GLContextResetNotification; +typedef Uint32 SDL_GLContextResetNotification; + +#define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000 +#define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001 + /* Function prototypes */ @@ -350,7 +511,9 @@ typedef enum SDL_GLContextResetNotification * * \returns the number of built in video drivers. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVideoDriver */ @@ -369,7 +532,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers */ @@ -385,7 +550,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); * \returns the name of the current video driver or NULL if no driver has been * initialized. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers * \sa SDL_GetVideoDriver @@ -397,7 +564,9 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void); * * \returns the current system theme, light, dark, or unknown. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); @@ -410,7 +579,9 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); * call SDL_GetError() for more information. This should be freed * with SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); @@ -420,7 +591,9 @@ extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count); * \returns the instance ID of the primary display on success or 0 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -448,7 +621,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void); * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID); @@ -462,7 +637,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa * \returns the name of a display or NULL on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -471,19 +648,22 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displa /** * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the usable desktop area represented by a display, in screen @@ -499,15 +679,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayI * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect); /** * Get the orientation of a display when it is unrotated. @@ -516,7 +698,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID di * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -529,7 +713,9 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -543,12 +729,21 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays */ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID); @@ -573,7 +768,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays */ @@ -587,7 +784,7 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * refresh rate default to the desktop mode if they are set to 0. The modes * are scanned with size being first priority, format being second priority, * and finally checking the refresh rate. If all the available modes are too - * small, then NULL is returned. + * small, then false is returned. * * \param displayID the instance ID of the display to query. * \param w the width in pixels of the desired display mode. @@ -596,17 +793,19 @@ extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL * for the desktop refresh rate. * \param include_high_density_modes boolean to include high density modes in * the search. - * \param mode a pointer filled in with the closest display mode equal to or - * larger than the desired mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param closest a pointer filled in with the closest display mode equal to + * or larger than the desired mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes, SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest); /** * Get information about the desktop's display mode. @@ -620,7 +819,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_Dis * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayMode * \sa SDL_GetDisplays @@ -639,7 +840,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD * \returns a pointer to the desktop display mode or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDisplays @@ -653,7 +856,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SD * \returns the instance ID of the display containing the point or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -668,7 +873,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point * closest to the center of the rect on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -683,7 +890,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect * * on success or 0 on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -701,7 +910,9 @@ extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *wi * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowDisplayScale */ @@ -725,7 +936,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window); * \returns the display scale, or 0.0f on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); @@ -743,24 +956,26 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window); * taken effect. * * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an - * SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new - * mode dimensions. + * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode + * dimensions. * * \param window the window to affect. * \param mode a pointer to the display mode to use, which can be NULL for * borderless fullscreen desktop mode, or one of the fullscreen * modes returned by SDL_GetFullscreenDisplayModes() to set an * exclusive fullscreen mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreen * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode); /** * Query the display mode to use when a window is visible at fullscreen. @@ -769,7 +984,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *win * \returns a pointer to the exclusive fullscreen mode to use or NULL for * borderless fullscreen desktop mode. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -785,7 +1002,9 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode( * SDL_GetError() for more information. This should be freed with * SDL_free() when it is no longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size); @@ -797,7 +1016,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, s * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window); @@ -811,7 +1032,9 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); @@ -870,7 +1093,7 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * corresponding UnloadLibrary function is called by SDL_DestroyWindow(). * * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver, - * SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail. + * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail. * * If SDL_WINDOW_METAL is specified on an OS that does not support Metal, * SDL_CreateWindow() will fail. @@ -890,8 +1113,11 @@ extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count); * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateWindowAndRenderer * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindowWithProperties * \sa SDL_DestroyWindow @@ -901,36 +1127,41 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int /** * Create a child popup window of the specified parent window. * - * 'flags' **must** contain exactly one of the following: - - * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any - * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu. - * The topmost popup menu will implicitly gain the keyboard focus. + * The flags parameter **must** contain at least one of the following: + * + * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any + * input events. + * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost + * popup menu will implicitly gain the keyboard focus. * * The following flags are not relevant to popup window creation and will be * ignored: * - * - 'SDL_WINDOW_MINIMIZED' - * - 'SDL_WINDOW_MAXIMIZED' - * - 'SDL_WINDOW_FULLSCREEN' - * - 'SDL_WINDOW_BORDERLESS' + * - `SDL_WINDOW_MINIMIZED` + * - `SDL_WINDOW_MAXIMIZED` + * - `SDL_WINDOW_FULLSCREEN` + * - `SDL_WINDOW_BORDERLESS` + * + * The following flags are incompatible with popup window creation and will + * cause it to fail: + * + * - `SDL_WINDOW_UTILITY` + * - `SDL_WINDOW_MODAL` * * The parent parameter **must** be non-null and a valid window. The parent of * a popup window can be either a regular, toplevel window, or another popup * window. * * Popup windows cannot be minimized, maximized, made fullscreen, raised, - * flash, be made a modal window, be the parent of a modal window, or grab the - * mouse and/or keyboard. Attempts to do so will fail. + * flash, be made a modal window, be the parent of a toplevel window, or grab + * the mouse and/or keyboard. Attempts to do so will fail. * * Popup windows implicitly do not have a border/decorations and do not appear * on the taskbar/dock or in lists of windows such as alt-tab menus. * - * If a parent window is hidden, any child popup windows will be recursively - * hidden as well. Child popup windows not explicitly hidden will be restored - * when the parent is shown. - * - * If the parent window is destroyed, any child popup windows will be - * recursively destroyed as well. + * If a parent window is hidden or destroyed, any child popup windows will be + * recursively hidden or destroyed as well. Child popup windows not explicitly + * hidden will be restored when the parent is shown. * * \param parent the parent of the window, must not be NULL. * \param offset_x the x position of the popup window relative to the origin @@ -944,7 +1175,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_CreateWindowWithProperties @@ -987,7 +1220,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used * with OpenGL rendering * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the - * parent of this window, required for windows with the "toolip", "menu", + * parent of this window, required for windows with the "tooltip", "menu", * and "modal" properties * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be * resizable @@ -1003,10 +1236,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * * These are additional supported properties on macOS: * @@ -1024,8 +1259,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * [README/wayland](README/wayland) for more information on using custom * surfaces. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the - * application wants an associated `wl_egl_window` object to be created, - * even if the window does not have the OpenGL property or flag set. + * application wants an associated `wl_egl_window` object to be created and + * attached to the window, even if the window does not have the OpenGL + * property or `SDL_WINDOW_OPENGL` flag set. * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface * associated with the window, if you want to wrap an existing window. See * [README/wayland](README/wayland) for more information. @@ -1061,7 +1297,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateWindow @@ -1114,7 +1352,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFromID */ @@ -1130,7 +1370,9 @@ extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window); * \returns the window associated with `id` or NULL if it doesn't exist; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowID */ @@ -1143,7 +1385,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id); * \returns the parent of the window on success or NULL if the window has no * parent. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow */ @@ -1181,7 +1425,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)` * UIWindow associated with the window * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag - * assocated with metal views on the window + * associated with metal views on the window * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's * framebuffer object. It must be bound when rendering to the screen using * OpenGL. @@ -1206,6 +1450,11 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag * assocated with metal views on the window * + * On OpenVR: + * + * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID`: the OpenVR Overlay Handle ID for the + * associated overlay window. + * * On Vivante: * * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType @@ -1215,11 +1464,6 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with * the window * - * On UWP: - * - * - `SDL_PROP_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow - * associated with the window - * * On Windows: * * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window @@ -1237,6 +1481,8 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * the window * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window * associated with the window * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated @@ -1263,7 +1509,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window) * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window); @@ -1283,15 +1531,16 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window #define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev" #define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window" #define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag" +#define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID "SDL.window.openvr.overlay_id" #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display" #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window" #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface" -#define SDL_PROP_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window" #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd" #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc" #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance" #define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display" #define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface" +#define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport" #define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window" #define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface" #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel" @@ -1308,7 +1557,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window * \param window the window to query. * \returns a mask of the SDL_WindowFlags associated with `window`. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_HideWindow @@ -1327,14 +1578,16 @@ extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *windo * * \param window the window to change. * \param title the desired window title in UTF-8 format. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowTitle */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title); /** * Get the title of a window. @@ -1343,7 +1596,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, cons * \returns the title of the window in UTF-8 format or "" if there is no * title. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowTitle */ @@ -1364,23 +1619,24 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window); * * \param window the window to change. * \param icon an SDL_Surface structure containing the icon for the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon); /** * Request that the window's position be set. * - * If, at the time of this request, the window is in a fixed-size state such - * as maximized, this request may be deferred until the window returns to a - * resizable state. + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. * * This can be used to reposition fullscreen-desktop windows onto a different - * display, however, exclusive fullscreen windows are locked to a specific - * display and can only be repositioned programmatically via + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via * SDL_SetWindowFullscreenMode(). * * On some windowing systems this request is asynchronous and the new @@ -1401,15 +1657,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_S * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or * `SDL_WINDOWPOS_UNDEFINED`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y); /** * Get the position of a window. @@ -1425,24 +1683,25 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, i * NULL. * \param y a pointer filled in with the y position of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowPosition */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y); /** * Request that the size of a window's client area be set. * - * If, at the time of this request, the window in a fixed-size state, such as - * maximized or fullscreen, the request will be deferred until the window - * exits this state and becomes resizable again. + * If the window is in a fullscreen or maximized state, this request has no + * effect. * - * To change the fullscreen mode of a window, use - * SDL_SetWindowFullscreenMode() + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). * * On some windowing systems, this request is asynchronous and the new window * size may not have have been applied immediately upon the return of this @@ -1459,16 +1718,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, i * \param window the window to change. * \param w the width of the window, must be > 0. * \param h the height of the window, must be > 0. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h); /** * Get the size of a window's client area. @@ -1480,16 +1741,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w * \param window the window to query the width and height from. * \param w a pointer filled in with the width of the window, may be NULL. * \param h a pointer filled in with the height of the window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize * \sa SDL_GetWindowSizeInPixels * \sa SDL_SetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); /** * Get the safe area for this window. @@ -1497,19 +1760,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int * * Some devices have portions of the screen which are partially obscured or * not interactive, possibly due to on-screen controls, curved edges, camera * notches, TV overscan, etc. This function provides the area of the window - * which is safe to have interactible content. You should continue rendering + * which is safe to have interactable content. You should continue rendering * into the rest of the window, but it should not contain visually important * or interactible content. * * \param window the window to query. * \param rect a pointer filled in with the client area that is safe for * interactive content. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect); /** * Request that the aspect ratio of a window's client area be set. @@ -1540,15 +1805,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, S * limit. * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no * limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect); /** * Get the size of a window's client area. @@ -1558,19 +1825,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window * window, may be NULL. * \param max_aspect a pointer filled in with the maximum aspect ratio of the * window, may be NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowAspectRatio */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect); /** * Get the size of a window's borders (decorations) around the client area. * - * Note: If this function fails (returns -1), the size values will be + * Note: If this function fails (returns false), the size values will be * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the * window in question was borderless. * @@ -1580,7 +1849,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * window has been presented and composited, so that the window system has a * chance to decorate the window and provide the border dimensions to SDL. * - * This function also returns -1 if getting the information is not supported. + * This function also returns false if getting the information is not + * supported. * * \param window the window to query the size values of the border * (decorations) from. @@ -1592,14 +1862,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window * border; NULL is permitted. * \param right pointer to variable for storing the size of the right border; * NULL is permitted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right); /** * Get the size of a window's client area, in pixels. @@ -1609,15 +1881,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window * NULL. * \param h a pointer to variable for storing the height in pixels, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h); /** * Set the minimum size of a window's client area. @@ -1625,15 +1899,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *windo * \param window the window to change. * \param min_w the minimum width of the window, or 0 for no limit. * \param min_h the minimum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h); /** * Get the minimum size of a window's client area. @@ -1643,15 +1919,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the minimum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h); /** * Set the maximum size of a window's client area. @@ -1659,15 +1937,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window * \param window the window to change. * \param max_w the maximum width of the window, or 0 for no limit. * \param max_h the maximum height of the window, or 0 for no limit. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h); /** * Get the maximum size of a window's client area. @@ -1677,15 +1957,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window * NULL. * \param h a pointer filled in with the maximum height of the window, may be * NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h); /** * Set the border state of a window. @@ -1697,15 +1979,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window * You can't change the border state of a fullscreen window. * * \param window the window of which to change the border state. - * \param bordered SDL_FALSE to remove border, SDL_TRUE to add border. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param bordered false to remove border, true to add border. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, SDL_bool bordered); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered); /** * Set the user-resizable state of a window. @@ -1717,15 +2001,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, S * You can't change the resizable state of a fullscreen window. * * \param window the window of which to change the resizable state. - * \param resizable SDL_TRUE to allow resizing, SDL_FALSE to disallow. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param resizable true to allow resizing, false to disallow. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, SDL_bool resizable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable); /** * Set the window to always be above the others. @@ -1734,43 +2020,49 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, * will bring the window to the front and keep the window above the rest. * * \param window the window of which to change the always on top state. - * \param on_top SDL_TRUE to set the window always on top, SDL_FALSE to - * disable. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param on_top true to set the window always on top, false to disable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, SDL_bool on_top); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top); /** * Show a window. * * \param window the window to show. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window); /** * Hide a window. * * \param window the window to hide. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window); /** * Request that a window be raised above other windows and gain the input @@ -1783,12 +2075,14 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HideWindow(SDL_Window *window); * the window will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window); /** * Request that the window be made as large as possible. @@ -1811,22 +2105,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RaiseWindow(SDL_Window *window); * and Wayland window managers may vary. * * \param window the window to maximize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MinimizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); /** * Request that the window be minimized to an iconic representation. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window - * state may not have have been applied immediately upon the return of this + * state may not have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to * block until the changes have taken effect. * @@ -1835,21 +2134,26 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MaximizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to minimize. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_RestoreWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); /** * Request that the size and position of a minimized or maximized window be * restored. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1860,16 +2164,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_MinimizeWindow(SDL_Window *window); * deny the state change. * * \param window the window to restore. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_MinimizeWindow * \sa SDL_SyncWindow */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window); /** * Request that the window's fullscreen state be changed. @@ -1888,18 +2194,20 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_RestoreWindow(SDL_Window *window); * is just a request, it can be denied by the windowing system. * * \param window the window to change. - * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed - * mode. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param fullscreen true for fullscreen mode, false for windowed mode. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen); /** * Block until any pending window state is finalized. @@ -1915,10 +2223,12 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * * \param window the window for which to wait for the pending state to be * applied. - * \returns SDL_TRUE on success or SDL_FALSE if the operation timed out before - * the window was in the requested state. + * \returns true on success or false if the operation timed out before the + * window was in the requested state. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSize * \sa SDL_SetWindowPosition @@ -1928,20 +2238,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, * \sa SDL_RestoreWindow * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SyncWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window); /** * Return whether the window has a surface associated with it. * * \param window the window to query. - * \returns SDL_TRUE if there is a surface associated with the window, or - * SDL_FALSE otherwise. + * \returns true if there is a surface associated with the window, or false + * otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); /** * Get the SDL surface associated with the window. @@ -1961,7 +2273,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WindowHasSurface(SDL_Window *window); * \returns the surface associated with the window, or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyWindowSurface * \sa SDL_WindowHasSurface @@ -1985,14 +2299,16 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *windo * * \param window the window. * \param vsync the vertical refresh sync interval. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync); #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1) @@ -2003,14 +2319,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *windo * \param window the window to query. * \param vsync an int filled with the current vertical refresh sync interval. * See SDL_SetWindowSurfaceVSync() for the meaning of the value. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSurfaceVSync */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync); /** * Copy the window surface to the screen. @@ -2021,15 +2339,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *windo * This function is equivalent to the SDL 1.2 API SDL_Flip(). * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window); /** * Copy areas of the window surface to the screen. @@ -2048,29 +2368,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window) * \param rects an array of SDL_Rect structures representing areas of the * surface to copy, in pixels. * \param numrects the number of rectangles. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); +extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects); /** * Destroy the surface associated with the window. * * \param window the window to update. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window); /** * Set a window's keyboard grab mode. @@ -2092,16 +2416,18 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window * other window loses its grab in favor of the caller's window. * * \param window the window for which the keyboard grab mode should be set. - * \param grabbed this is SDL_TRUE to grab keyboard, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab keyboard, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed); /** * Set a window's mouse grab mode. @@ -2109,47 +2435,60 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *windo * Mouse grab confines the mouse cursor to the window. * * \param window the window for which the mouse grab mode should be set. - * \param grabbed this is SDL_TRUE to grab mouse, and SDL_FALSE to release. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param grabbed this is true to grab mouse, and false to release. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * - * \sa SDL_GetWindowMouseGrab + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, SDL_bool grabbed); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed); /** * Get a window's keyboard grab mode. * * \param window the window to query. - * \returns SDL_TRUE if keyboard is grabbed, and SDL_FALSE otherwise. + * \returns true if keyboard is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window); /** * Get a window's mouse grab mode. * * \param window the window to query. - * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise. + * \returns true if mouse is grabbed, and false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window); /** * Get the window that currently has an input grab enabled. * * \returns the window if input is grabbed or NULL otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab @@ -2165,15 +2504,18 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void); * \param window the window that will be associated with the barrier. * \param rect a rectangle area in window-relative coordinates. If NULL the * barrier for the specified window will be destroyed. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowMouseGrab */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect); /** * Get the mouse confinement rectangle of a window. @@ -2182,9 +2524,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, * \returns a pointer to the mouse confinement rectangle of a window, or NULL * if there isn't one. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab */ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window); @@ -2194,18 +2540,20 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * * The parameter `opacity` will be clamped internally between 0.0f * (transparent) and 1.0f (opaque). * - * This function also returns -1 if setting the opacity isn't supported. + * This function also returns false if setting the opacity isn't supported. * * \param window the window which will be made transparent or opaque. * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque). - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowOpacity */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity); /** * Get the opacity of a window. @@ -2217,43 +2565,81 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, fl * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowOpacity */ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window); /** - * Set the window as a modal to a parent window. + * Set the window as a child of a parent window. * - * If the window is already modal to an existing window, it will be reparented - * to the new owner. Setting the parent window to null unparents the modal - * window and removes modal status. + * If the window is already the child of an existing window, it will be + * reparented to the new owner. Setting the parent window to NULL unparents + * the window and removes child window status. * - * Setting a window as modal to a parent that is a descendent of the modal - * window results in undefined behavior. + * If a parent window is hidden or destroyed, the operation will be + * recursively applied to child windows. Child windows hidden with the parent + * that did not have their hidden status explicitly set will be restored when + * the parent is shown. * - * \param modal_window the window that should be set modal. - * \param parent_window the parent window for the modal window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * Attempting to set the parent of a window that is currently in the modal + * state will fail. Use SDL_SetWindowModal() to cancel the modal status before + * attempting to change the parent. * - * \since This function is available since SDL 3.0.0. + * Popup windows cannot change parents and attempts to do so will fail. + * + * Setting a parent window that is currently the sibling or descendent of the + * child window results in undefined behavior. + * + * \param window the window that should become the child of a parent. + * \param parent the new parent window for the child window. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowModal */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowModalFor(SDL_Window *modal_window, SDL_Window *parent_window); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent); + +/** + * Toggle the state of the window as modal. + * + * To enable modal status on a window, the window must currently be the child + * window of a parent, or toggling modal status on will fail. + * + * \param window the window on which to set the modal state. + * \param modal true to toggle modal status on, false to toggle it off. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL + */ +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal); /** * Set whether the window may have input focus. * * \param window the window to set focusable state. - * \param focusable SDL_TRUE to allow input focus, SDL_FALSE to not allow - * input focus. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \param focusable true to allow input focus, false to not allow input focus. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, SDL_bool focusable); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable); /** @@ -2272,17 +2658,21 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, * the client area. * \param y the y coordinate of the menu, relative to the origin (top-left) of * the client area. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); +extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y); /** * Possible return values from the SDL_HitTest callback. * - * \since This enum is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This enum is available since SDL 3.2.0. * * \sa SDL_HitTest */ @@ -2335,7 +2725,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * Specifying NULL for a callback disables hit-testing. Hit-testing is * disabled by default. * - * Platforms that don't support this functionality will return SDL_FALSE + * Platforms that don't support this functionality will return false * unconditionally, even if you're attempting to disable hit-testing. * * Your callback may fire at any time, and its firing does not indicate any @@ -2349,58 +2739,72 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * \param window the window to set hit-testing on. * \param callback the function to call when doing a hit-test. * \param callback_data an app-defined void pointer passed to **callback**. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data); /** * Set the shape of a transparent window. * * This sets the alpha channel of a transparent window and any fully * transparent areas are also transparent to mouse clicks. If you are using - * something besides the SDL render API, then you are responsible for setting - * the alpha channel of the window yourself. + * something besides the SDL render API, then you are responsible for drawing + * the alpha channel of the window to match the shape alpha channel to get + * consistent cross-platform results. * * The shape is copied inside this function, so you can free it afterwards. If * your shape surface changes, you should call SDL_SetWindowShape() again to - * update the window. + * update the window. This is an expensive operation, so should be done + * sparingly. * * The window must have been created with the SDL_WINDOW_TRANSPARENT flag. * * \param window the window. * \param shape the surface representing the shape of the window, or NULL to * remove any current shape. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); +extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape); /** * Request a window to demand attention from the user. * * \param window the window to be flashed. * \param operation the operation to perform. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); +extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation); /** * Destroy a window. * - * Any popups or modal windows owned by the window will be recursively - * destroyed as well. + * Any child windows owned by the window will be recursively destroyed as + * well. + * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. * * \param window the window to destroy. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindow @@ -2416,28 +2820,31 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window); * * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`. * - * \returns SDL_TRUE if the screensaver is enabled, SDL_FALSE if it is - * disabled. + * \returns true if the screensaver is enabled, false if it is disabled. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenSaverEnabled(void); +extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void); /** * Allow the screen to be blanked by a screen saver. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void); /** * Prevent the screen from being blanked by a screen saver. @@ -2448,15 +2855,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_EnableScreenSaver(void); * The screensaver is disabled by default, but this may by changed by * SDL_HINT_VIDEO_ALLOW_SCREENSAVER. * - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); +extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void); /** @@ -2476,15 +2885,17 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_DisableScreenSaver(void); * * \param path the platform dependent OpenGL library name, or NULL to open the * default OpenGL library. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path); /** * Get an OpenGL function by name. @@ -2531,7 +2942,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_LoadLibrary(const char *path); * \returns a pointer to the named OpenGL function. The returned pointer * should be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ExtensionSupported * \sa SDL_GL_LoadLibrary @@ -2550,7 +2963,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char * \returns a pointer to the named EGL function. The returned pointer should * be cast to the appropriate function signature. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EGL_GetCurrentDisplay */ @@ -2559,7 +2974,9 @@ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const cha /** * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_LoadLibrary */ @@ -2580,16 +2997,20 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void); * every time you need to know. * * \param extension the name of the extension to check. - * \returns SDL_TRUE if the extension is supported, SDL_FALSE otherwise. + * \returns true if the extension is supported, false otherwise. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension); /** * Reset all previously set OpenGL context attributes to their default values. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute @@ -2604,34 +3025,38 @@ extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void); * SDL_GL_GetAttribute() to check the values after creating the OpenGL * context, since the values obtained can differ from the requested ones. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * set. * \param value the desired value for the attribute. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value); /** * Get the actual value for an attribute from the current context. * - * \param attr an SDL_GLattr enum value specifying the OpenGL attribute to + * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to * get. * \param value a pointer filled in with the current value of `attr`. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value); /** * Create an OpenGL context for an OpenGL window, and make it current. @@ -2648,7 +3073,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *v * \returns the OpenGL context associated with `window` or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_DestroyContext * \sa SDL_GL_MakeCurrent @@ -2662,14 +3089,16 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *windo * * \param window the window to associate with the context. * \param context the OpenGL context to associate with the window. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context); /** * Get the currently active OpenGL window. @@ -2677,7 +3106,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_ * \returns the currently active OpenGL window on success or NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); @@ -2687,7 +3118,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void); * \returns the currently active OpenGL context or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_MakeCurrent */ @@ -2699,7 +3132,9 @@ extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * \returns the currently active EGL display or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); @@ -2709,7 +3144,9 @@ extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void); * \returns the currently active EGL config or NULL on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); @@ -2720,7 +3157,9 @@ extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void); * \returns the EGLSurface pointer associated with the window, or NULL on * failure. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window); @@ -2728,27 +3167,25 @@ extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window * * Sets the callbacks for defining custom EGLAttrib arrays for EGL * initialization. * - * Each callback should return a pointer to an EGL attribute array terminated - * with EGL_NONE. Callbacks may return NULL pointers to signal an error, which - * will cause the SDL_CreateWindow process to fail gracefully. - * - * The arrays returned by each callback will be appended to the existing - * attribute arrays defined by SDL. + * Callbacks that aren't needed can be set to NULL. * * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes. * * \param platformAttribCallback callback for attributes to pass to - * eglGetPlatformDisplay. + * eglGetPlatformDisplay. May be NULL. * \param surfaceAttribCallback callback for attributes to pass to - * eglCreateSurface. + * eglCreateSurface. May be NULL. * \param contextAttribCallback callback for attributes to pass to - * eglCreateContext. + * eglCreateContext. May be NULL. + * \param userdata a pointer that is passed to the callbacks. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback, - SDL_EGLIntArrayCallback surfaceAttribCallback, - SDL_EGLIntArrayCallback contextAttribCallback); + SDL_EGLIntArrayCallback surfaceAttribCallback, + SDL_EGLIntArrayCallback contextAttribCallback, void *userdata); /** * Set the swap interval for the current OpenGL context. @@ -2758,7 +3195,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * the vertical retrace for a given frame, it swaps buffers immediately, which * might be less jarring for the user during occasional framerate drops. If an * application requests adaptive vsync and the system does not support it, - * this function will fail and return SDL_FALSE. In such a case, you should + * this function will fail and return false. In such a case, you should * probably retry the call with 1 for the interval. * * Adaptive vsync is implemented for some glX drivers with @@ -2770,14 +3207,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArra * * \param interval 0 for immediate updates, 1 for updates synchronized with * the vertical retrace, -1 for adaptive vsync. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval); /** * Get the swap interval for the current OpenGL context. @@ -2789,14 +3228,16 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SetSwapInterval(int interval); * synchronization, 1 if the buffer swap is synchronized with * the vertical retrace, and -1 if late swaps happen * immediately instead of waiting for the next retrace. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_SetSwapInterval */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval); /** * Update a window with OpenGL rendering. @@ -2809,25 +3250,29 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_GetSwapInterval(int *interval); * extra. * * \param window the window to change. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window); /** * Delete an OpenGL context. * * \param context the OpenGL context to be deleted. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); +extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context); /* @} *//* OpenGL support functions */ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h index c31d33c..5a48756 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Headers/SDL_vulkan.h @@ -23,11 +23,25 @@ * # CategoryVulkan * * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. */ #ifndef SDL_vulkan_h_ #define SDL_vulkan_h_ +#include #include #include @@ -55,6 +69,10 @@ VK_DEFINE_HANDLE(VkPhysicalDevice) VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) struct VkAllocationCallbacks; +/* Make sure to undef to avoid issues in case of later vulkan include */ +#undef VK_DEFINE_HANDLE +#undef VK_DEFINE_NON_DISPATCHABLE_HANDLE + #endif /* !NO_SDL_VULKAN_TYPEDEFS */ /** @@ -69,6 +87,13 @@ struct VkAllocationCallbacks; * creating any Vulkan windows. If no Vulkan loader library is loaded, the * default library will be loaded upon creation of the first Vulkan window. * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * * It is fairly common for Vulkan applications to link with libvulkan instead * of explicitly loading it at run time. This will work with SDL provided the * application links to a dynamic library and both it and SDL use the same @@ -95,15 +120,17 @@ struct VkAllocationCallbacks; * library version. * * \param path the platform dependent Vulkan loader library name or NULL. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); /** * Get the address of the `vkGetInstanceProcAddr` function. @@ -122,14 +149,27 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_LoadLibrary(const char *path); * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); /** * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). * - * \since This function is available since SDL 3.0.0. + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_LoadLibrary */ @@ -153,7 +193,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * \returns an array of extension name strings on success, NULL on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_CreateSurface */ @@ -175,15 +215,15 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension * allocator that creates the surface. Can be NULL. * \param surface a pointer to a VkSurfaceKHR handle to output the newly * created surface. - * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() - * for more information. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_DestroySurface */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, VkInstance instance, const struct VkAllocationCallbacks *allocator, VkSurfaceKHR* surface); @@ -206,7 +246,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window * \param allocator a VkAllocationCallbacks struct, which lets the app set the * allocator that destroys the surface. Can be NULL. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions * \sa SDL_Vulkan_CreateSurface @@ -226,14 +266,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_DestroySurface(VkInstance instance, * \param physicalDevice a valid Vulkan physical device handle. * \param queueFamilyIndex a valid queue family index for the given physical * device. - * \returns SDL_TRUE if supported, SDL_FALSE if unsupported or an error - * occurred. + * \returns true if supported, false if unsupported or an error occurred. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Vulkan_GetInstanceExtensions */ -extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, +extern SDL_DECLSPEC bool SDLCALL SDL_Vulkan_GetPresentationSupport(VkInstance instance, VkPhysicalDevice physicalDevice, Uint32 queueFamilyIndex); diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/INSTALL.md b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/INSTALL.md new file mode 100644 index 0000000..97e4ab6 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/INSTALL.md @@ -0,0 +1,41 @@ + +# Using this package + +This package contains SDL built for Xcode. + +To use this package in Xcode, drag `SDL3.framework` into your project. + +# Documentation + +An API reference, tutorials, and additional documentation is available at: + +https://wiki.libsdl.org/SDL3 + +# Example code + +There are simple example programs available at: + +https://examples.libsdl.org/SDL3 + +# Discussions + +## Discord + +You can join the official Discord server at: + +https://discord.com/invite/BwpFGBWsv8 + +## Forums/mailing lists + +You can join SDL development discussions at: + +https://discourse.libsdl.org/ + +Once you sign up, you can use the forum through the website or as a mailing list from your email client. + +## Announcement list + +You can sign up for the low traffic announcement list at: + +https://www.libsdl.org/mailing-list.php + diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Info.plist b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Info.plist index 9c6b81b..9bcb89f 100644 Binary files a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Info.plist and b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/Info.plist differ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/License.txt b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/License.txt index 42f3736..23abb73 100644 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/License.txt +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/License.txt @@ -1,6 +1,4 @@ - -Simple DirectMedia Layer -Copyright (C) 1997-2024 Sam Lantinga +Copyright (C) 1997-2025 Sam Lantinga This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -17,3 +15,4 @@ freely, subject to the following restrictions: 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. + diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/README.md b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/README.md new file mode 100644 index 0000000..68b0923 --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/README.md @@ -0,0 +1,17 @@ + +Simple DirectMedia Layer (SDL for short) is a cross-platform library +designed to make it easy to write multi-media software, such as games +and emulators. + +You can find the latest release and additional information at: +https://www.libsdl.org/ + +Installation instructions and a quick introduction is available in +[INSTALL.md](INSTALL.md) + +This library is distributed under the terms of the zlib license, +available in [LICENSE.txt](LICENSE.txt). + +Enjoy! + +Sam Lantinga (slouken@libsdl.org) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/ReadMe.txt b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/ReadMe.txt deleted file mode 100644 index 6ea9347..0000000 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/ReadMe.txt +++ /dev/null @@ -1,44 +0,0 @@ -The Simple DirectMedia Layer (SDL for short) is a cross-platform -library designed to make it easy to write multi-media software, -such as games and emulators. - -The Simple DirectMedia Layer library source code is available from: -http://www.libsdl.org/ - -This library is distributed under the terms of the zlib license: -http://zlib.net/zlib_license.html - - -This packages contains the SDL framework for macOS. -Conforming with Apple guidelines, this framework -contains both the SDL runtime component and development header files. - - -To Install: -Copy "SDL3.xcframework" and "share" to /Library/Frameworks - -You may alternatively install it in /Library/Frameworks -if your access privileges are not high enough. - - -Use in CMake projects: -SDL3.xcframework can be used in CMake projects using the following pattern: -```cmake -find_package(SDL3 REQUIRED COMPONENTS SDL3) -add_executable(my_game ${MY_SOURCES}) -target_link_libraries(my_game PRIVATE SDL3::SDL3) -``` -If SDL3.framework is installed in a non-standard location, -please refer to the following link for ways to configure CMake: -https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure - - -Additional References: - - - Screencast tutorials for getting started with OpenSceneGraph/macOS are - available at: - http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips - Though these are OpenSceneGraph centric, the same exact concepts apply to - SDL, thus the videos are recommended for everybody getting started with - developing on macOS. (You can skim over the PlugIns stuff since SDL - doesn't have any PlugIns to worry about.) diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/SDL3 b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/SDL3 index c6e2530..09f9c45 100755 Binary files a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/SDL3 and b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/SDL3 differ diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/_CodeSignature/CodeResources b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/_CodeSignature/CodeResources new file mode 100644 index 0000000..2383d9a --- /dev/null +++ b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/_CodeSignature/CodeResources @@ -0,0 +1,982 @@ + + + + + files + + CMake/SDL3Config.cmake + + wVPzCDAGpS2036XQsVLmiAOr8Bc= + + CMake/SDL3ConfigVersion.cmake + + gQ+LV+T54JMbmVqczZwWryOwVns= + + Headers/SDL.h + + lZ3h7l/TqUrTiXHgV15X4SmQdlg= + + Headers/SDL_assert.h + + FCAIhbQEN4FmvTlBQOOPjycjnzo= + + Headers/SDL_asyncio.h + + fGXNFcOElD6IRbX9GcJubLmoorU= + + Headers/SDL_atomic.h + + ZSetO9pGvnFdg6kNoQWBa42rYug= + + Headers/SDL_audio.h + + 4mdiUNQEXHRPqAT1Tyq7aFbrCz4= + + Headers/SDL_begin_code.h + + wsAzfk5ARMtwSG4xPvzg5m3Jz8U= + + Headers/SDL_bits.h + + 9cqOFvZxXmGK7a5xO8Lz50q6zok= + + Headers/SDL_blendmode.h + + usmRnfDgT4dxC8NUBkBLHOFce94= + + Headers/SDL_camera.h + + zHEfe8mk7gUo10V9SZo8ehQDUlY= + + Headers/SDL_clipboard.h + + UREK6p3Z6taOQm4qRmug/UrLLX8= + + Headers/SDL_close_code.h + + 1vBg1G1kDxz48iNCRQzRs4JdJXo= + + Headers/SDL_copying.h + + qgiizcHDSADGW6sbUWVXBnHDWIM= + + Headers/SDL_cpuinfo.h + + rjGkZeoG408swy+z8MRwRTXE4/A= + + Headers/SDL_dialog.h + + wRwxojHRWHS7ZY+00Ugcp+ulhVc= + + Headers/SDL_egl.h + + 2TRm4qSC+lwUqk357LIp+9RA5D0= + + Headers/SDL_endian.h + + zuQm4k5QRLG+8gYrpjTaHyKdwJo= + + Headers/SDL_error.h + + 2qWxaJQ1wp4at9K8sk+FAfpf0ig= + + Headers/SDL_events.h + + srOwCYOhw2wJ3y4TDfHmDSyCFwA= + + Headers/SDL_filesystem.h + + x2Bf0NH1HhevHFcwIIhsi1nsUlk= + + Headers/SDL_gamepad.h + + GD829JbTWBtzqqDEb8K+Kak1alU= + + Headers/SDL_gpu.h + + VUeK6nT8fg94fv2ahh3v/H6bFv0= + + Headers/SDL_guid.h + + PbhQca/PTObFyBpF0YADyZ4UxgU= + + Headers/SDL_haptic.h + + cnzDmGxX9Q613k0BUk0+kxDB/mY= + + Headers/SDL_hidapi.h + + s2YTW3pfACVyMAnkvHvbUGwbrAo= + + Headers/SDL_hints.h + + AEwxf+T99FHEv/c3SLJX3G9ZAkc= + + Headers/SDL_init.h + + 1cF9UGNdMfWCaGTFPnDilOcmbdY= + + Headers/SDL_intrin.h + + j14ekg6zAs7gojHrq8YuNsg5ftU= + + Headers/SDL_iostream.h + + INQzKo+TXazvwu2uSIXTk74A4Ms= + + Headers/SDL_joystick.h + + Dj3PmhA77DmQhaaO7TtlFVfr8Fk= + + Headers/SDL_keyboard.h + + TA2CXW0WZtojbbbD8QO5YbCtYk0= + + Headers/SDL_keycode.h + + Vep2hlXhJj2m5WJUv3YSjgwZJig= + + Headers/SDL_loadso.h + + 5kT/8rtuphyE7R7qRnWTSM3vZD8= + + Headers/SDL_locale.h + + wdVGs4oraONMu+OI1Vq89eCwgRI= + + Headers/SDL_log.h + + fchtNGMinx43j8vDGByzEG8Ug5o= + + Headers/SDL_main.h + + 5RmWvYVo9aeKVojTkH6+BW51UFQ= + + Headers/SDL_main_impl.h + + B5urjdx8niHPF6lzVXVl0e513EM= + + Headers/SDL_messagebox.h + + eLiKcRb2KqDF+NiOCLTypsmVW9c= + + Headers/SDL_metal.h + + JQbRAPxnIekwgyOzk9jNdyTrw5g= + + Headers/SDL_misc.h + + o0Zdf1k3zVEwjCK20nnKd0mE3Tk= + + Headers/SDL_mouse.h + + 5LuKu9JO0epHU72XAQi6XzeITWw= + + Headers/SDL_mutex.h + + zC93pUcPmlFIS9L8r4ciCvJm0mk= + + Headers/SDL_oldnames.h + + LVEh0rWKvPoz0Olpe7Opq43B+/Q= + + Headers/SDL_opengl.h + + nBXVdw/GJ7GDEMLjNVChtFKnnhc= + + Headers/SDL_opengl_glext.h + + TvPj1ofjtpSE6KgrLAh6PnGyZNQ= + + Headers/SDL_opengles.h + + GVQefc+XmHojZPonePHo3DmwzMw= + + Headers/SDL_opengles2.h + + y2MDVf0VqmkxR9HtNdwVas9bsig= + + Headers/SDL_opengles2_gl2.h + + GbD4M9ZIR9sxgLX4G8T/ojLVQJk= + + Headers/SDL_opengles2_gl2ext.h + + frTvd+EfShO/uonAvnnsnPkqc80= + + Headers/SDL_opengles2_gl2platform.h + + JO1DB28zz7TCz/P5YCSvV1PaqWg= + + Headers/SDL_opengles2_khrplatform.h + + mBjqEs+5bGC9u1ED2M93VNzONPQ= + + Headers/SDL_pen.h + + EXvVo7r3v4Js0CLNoAx2CfU2yFw= + + Headers/SDL_pixels.h + + sAQtWWQrbFCZTpncKsMKtnFHS1k= + + Headers/SDL_platform.h + + O0WfapqV4/M3w8tAMcj2VbsPg5M= + + Headers/SDL_platform_defines.h + + 6daGsbgvToo48b6YvBOq9M9sc3c= + + Headers/SDL_power.h + + JjIeT6uo0ADVc48kia7YbS4w6/s= + + Headers/SDL_process.h + + kekhaSL6DFc1U1O4u9PvL3gg4aw= + + Headers/SDL_properties.h + + gb6Lko32APlCWI0MC2wu4I/SQB4= + + Headers/SDL_rect.h + + y1wXNIYEgFi/LZPZLJi3Nh/6tso= + + Headers/SDL_render.h + + QzDPmDedVEINEMr8F1kzJJI9jyA= + + Headers/SDL_revision.h + + aoq5eTEZpac8JzGqebvXrvJ508w= + + Headers/SDL_scancode.h + + NCaX6yHdGwkjQ+1XlCxEpOE6KJo= + + Headers/SDL_sensor.h + + RwfqWMNjZi8O6c/e7f+l6jrWWtU= + + Headers/SDL_stdinc.h + + p5U44ukHJeOXMWHOrkm307yjChQ= + + Headers/SDL_storage.h + + KXFZhty0OaDdpkyS4U2oixZAfss= + + Headers/SDL_surface.h + + AISVaeDCftEr8gDdHW1m7ve+w5k= + + Headers/SDL_system.h + + qqeS48QOHWmApVD4vlK6r0esuqM= + + Headers/SDL_thread.h + + zzmAf2qJ9VWWB9mcS42yX6E+B0k= + + Headers/SDL_time.h + + 8B2GEH3aRj2suI7hviE/di1h4Cw= + + Headers/SDL_timer.h + + Dw3rK6vs8TgCHBqN7xNPdWp1ea4= + + Headers/SDL_touch.h + + D8Tmyow63hNMy9jEvRnaAaO1FrQ= + + Headers/SDL_tray.h + + vALAlZwywLFvWYtZOh8/39bZGtU= + + Headers/SDL_version.h + + kVdgSafPFSJe8BpriVdZkRe/57s= + + Headers/SDL_video.h + + irhtLqDbGK/7KCNTI2B3h3FCMps= + + Headers/SDL_vulkan.h + + MCL+LabbSXzNtmH4coS9Ea+8s9M= + + INSTALL.md + + fyUlqOEcE7zuLv8JGb0kUDRY4lc= + + Info.plist + + 4SaLTJ2cBZ9cFH8DQ44/QihdFBo= + + LICENSE.txt + + MV/H0zYdw5DZw6QWBIZwa65FY04= + + README.md + + ED8RfQwxZj7wFttxnetM9Q6jXX4= + + default.metallib + + HB6r8cBqLu2vNhxoebWg8H/eIwU= + + + files2 + + CMake/SDL3Config.cmake + + hash2 + + 0X7VyiYqUwqsTjqO580GDglfMgEgRhK7uFFUgPccqrk= + + + CMake/SDL3ConfigVersion.cmake + + hash2 + + o4od03lMXeFmSf7XQVrg+cMoEnzDAA0bJIE6oslEQe0= + + + Headers/SDL.h + + hash2 + + Cvdi4gF6iiTrPFFXBN8WVYzKuQogVno9ER2HjYHLD78= + + + Headers/SDL_assert.h + + hash2 + + GUKvmslH9JBDeZwVHFV+dJ7uRugCENjA2fi0NvkXP6o= + + + Headers/SDL_asyncio.h + + hash2 + + 6eQHTxs1vaIfPh2XJZ8Dxl4txtqcXyGNKYkEdckwbaY= + + + Headers/SDL_atomic.h + + hash2 + + PgrpKCw7TgKe8KHwM5rZiv5NmW9QXjmnbtbdlhWZpjk= + + + Headers/SDL_audio.h + + hash2 + + VvBp9u2lRJVv9qyun1cSYcFrEcFfxL8Sug+lFgPr6zU= + + + Headers/SDL_begin_code.h + + hash2 + + fxk2E7HjevknSqJuM6gdTVdk729oKqu6dGiIKlngKOI= + + + Headers/SDL_bits.h + + hash2 + + H88Gt0fGZ+U7ts+dAX1avFoprYg8Be7fz7AhxXG2FZI= + + + Headers/SDL_blendmode.h + + hash2 + + hAasxDnDlaxJ6necLTgqEtqXgyUxOY9o6DttaAzAP8U= + + + Headers/SDL_camera.h + + hash2 + + QVRcv5xfFyaG/Co9MnzrUy3C0NEo16s3zIbl6UwkUuw= + + + Headers/SDL_clipboard.h + + hash2 + + nm+rMDYWWqbnVnJ9sg8fShfLgFD1nALxB8KsBdNTuRU= + + + Headers/SDL_close_code.h + + hash2 + + zjynPn/VKTMQ/RVWksWLXoLlFvGoJn+E0K9XLIOY4+k= + + + Headers/SDL_copying.h + + hash2 + + ZENtUHjWdC8RyLCs+LyHI30V2jZxbrJVKYaotFxBmWc= + + + Headers/SDL_cpuinfo.h + + hash2 + + wDNjucbJP3UbWyU9Y2IIuqnWZYxpJoArNRaXNrlvGu8= + + + Headers/SDL_dialog.h + + hash2 + + uSXny36TRgIvEu9/b3g7AVOwfCSVETRcNiyye6ptSMU= + + + Headers/SDL_egl.h + + hash2 + + ZI1DHIxRuv6skDbbF8PuX96mtre4/huG2LdUFjDXzds= + + + Headers/SDL_endian.h + + hash2 + + 37jA4lsA1YiTsAWGk5vvZj/H/tf4+yDoCf7vcJa9Ew0= + + + Headers/SDL_error.h + + hash2 + + fSlLo+mUuJpCvGNG5+Wb/4L7zi0FD3zbGJ2PRfMXlfI= + + + Headers/SDL_events.h + + hash2 + + 6B7T1/y4oKgsbog2B2QL6UZ4vv4UnNRnk1Lhi807z3Q= + + + Headers/SDL_filesystem.h + + hash2 + + bR6AD/KyDeLQQW98aBfdbxGzufw7+4C+WDTjBpRmy9I= + + + Headers/SDL_gamepad.h + + hash2 + + TGeZjBGUlOjcgkIzBwKK2YpN508+deGN8RMmwTx3hRI= + + + Headers/SDL_gpu.h + + hash2 + + 2tUSvuo5Ev+GaOaDzcaLUYmJT5z1/Qxi4rfF/ejz4IE= + + + Headers/SDL_guid.h + + hash2 + + lYJzCv4bmAURGxZ8Yv7DmXsFLoA0VShvmZPDA8M6z7U= + + + Headers/SDL_haptic.h + + hash2 + + qLujijGSmObisRAEHA+3sUS2/sicBu5CiFRULbc9tw8= + + + Headers/SDL_hidapi.h + + hash2 + + BS/UNHgeoUgUP0ZE7Wr1ElicSkMtMcXZRy0vOU1OsWs= + + + Headers/SDL_hints.h + + hash2 + + zZW0/QZMSL38EomWyrpmd/wrv5wgUFUbQL1T+Liy/fE= + + + Headers/SDL_init.h + + hash2 + + X1qr3eJdWv9RNxQK9U/hAHM/7fyvLI8fbHE4pQqdSIo= + + + Headers/SDL_intrin.h + + hash2 + + YlLnI56pNm7vQnEwH6oDfki+eqMkQ0FPStKovXGGxmY= + + + Headers/SDL_iostream.h + + hash2 + + 2wZxMiUAboSqkmYgGObh9demGS4uXGetGIOddzOoBxU= + + + Headers/SDL_joystick.h + + hash2 + + r0aPy8paE7O55PiB3ku4l++dZITgfb2mBLYkZXPzg7U= + + + Headers/SDL_keyboard.h + + hash2 + + QMAEiiN+f9SUaPFtczb4DFrl44iMPNHXveQxWfYGgq0= + + + Headers/SDL_keycode.h + + hash2 + + CGHx7BS7/S7d8qMTXN1PVcyq+oGig+V0AjbvTRDo5wA= + + + Headers/SDL_loadso.h + + hash2 + + LucDpNvlT+qEmAE0wm0hy4fDDfS3r9+ho8xspu9k4J4= + + + Headers/SDL_locale.h + + hash2 + + s0UA/AyUaFIR/UxuFbAnLzul37UAYEB8OQHGyemDmFs= + + + Headers/SDL_log.h + + hash2 + + 0ypVf/5dM6mKA3D2BbkFRVoQaIuqUEDMEu1d5a59kak= + + + Headers/SDL_main.h + + hash2 + + dExUeHgHxUtHVpvJKFF6GLiPaRKS2UZ84V8JwgNYn/c= + + + Headers/SDL_main_impl.h + + hash2 + + nLJhKmOzMf/3oNn8MHvp28Ph8hx7CuZOgYGvyxa0Fg8= + + + Headers/SDL_messagebox.h + + hash2 + + f9JqShergM7ApYxHQJp0rMwnRA2TW3m1COEQmJgrwMg= + + + Headers/SDL_metal.h + + hash2 + + 7Fs5+iU7qLHNh8XkDvbeNtwypYjyDVB4sBEoASSwgkA= + + + Headers/SDL_misc.h + + hash2 + + zlOAZjhmbs3kUq4/i86aZTyFOf54uMb9lYW9SIjsk+A= + + + Headers/SDL_mouse.h + + hash2 + + YjZ7PHxJHE7eO4DD5IZ1dJmRmr1AK94SCg+xivpEFqw= + + + Headers/SDL_mutex.h + + hash2 + + K0mA/DdrF5+fAYkt6vZ5qNonce+zAecF0f+2ay6eciU= + + + Headers/SDL_oldnames.h + + hash2 + + pGGsTEnGS1qN38nfrQooK1X/CM4p6EhYwHuSrUCuZCE= + + + Headers/SDL_opengl.h + + hash2 + + LqWxBvkb9UooP3YdPv2hhaUV7Z1hcCrHNXJ0kg5pIC4= + + + Headers/SDL_opengl_glext.h + + hash2 + + 2IXkrwf1MIPKwa6QphzLOTF5R+5z5SFlBvsl9q5QMyQ= + + + Headers/SDL_opengles.h + + hash2 + + q8cYr3RT0WnR58ff37XZOaJQUZvuAt99QuDWplt+DIU= + + + Headers/SDL_opengles2.h + + hash2 + + 0ENhHFweBuRmpiO4jR7kmHRilduMwfFfGHLBl0IEUhc= + + + Headers/SDL_opengles2_gl2.h + + hash2 + + 1uxEsdc/OvzjogrGl223+z2sZWxRkPC1Y+TOkNeaFao= + + + Headers/SDL_opengles2_gl2ext.h + + hash2 + + T8WwA03N6cElki4+cNAUiaazNQdoVu5mApThpjBaNxk= + + + Headers/SDL_opengles2_gl2platform.h + + hash2 + + R3m+mZrNGQRFgjjwnIaYO3lgrEDmEuBdstuX22FfHg8= + + + Headers/SDL_opengles2_khrplatform.h + + hash2 + + ex4Bqqetj2/DS1x733nr9RibsJ4sTS55/F01BiPRHoM= + + + Headers/SDL_pen.h + + hash2 + + kMVe4rIilC0D2bCBXaQuTbyJcfYuFB6NF2zY0GMHZSc= + + + Headers/SDL_pixels.h + + hash2 + + LNF1mr8/q/ySYmhjN3BTRHUt8uoP0y2eaqGUSd01l1Q= + + + Headers/SDL_platform.h + + hash2 + + rJzzCb3cDnVV++HUJYN7rROraIegCilBvo1PzfSzERo= + + + Headers/SDL_platform_defines.h + + hash2 + + 1gY0D+xDbD99hyMrgCSftn/D98qE6Yzn384cCqguVQU= + + + Headers/SDL_power.h + + hash2 + + d9umbBzotQlz1MRiww4CcbV9plDfGYfg3LaoLI3Scro= + + + Headers/SDL_process.h + + hash2 + + Z6C8A6FVpoIFvmXDeVS57eD4WN5vSQcIcaKjUB9vmAQ= + + + Headers/SDL_properties.h + + hash2 + + FMSMnEfaIzvmuD/o5CBL6rhd6pXGuhrkjmSQ1F6mTt8= + + + Headers/SDL_rect.h + + hash2 + + dlouxLVTArPG98yxRQqcSEB/uMsozkfdcpTtRIU4Ojs= + + + Headers/SDL_render.h + + hash2 + + TTzckAGMIupcnJuLd1+U5SiZgRfytR/bTs1yRoWV56E= + + + Headers/SDL_revision.h + + hash2 + + kzj2kc5o0jOr8L5Dp5XLTtDRK+/WBebI7bVi3oVcjqA= + + + Headers/SDL_scancode.h + + hash2 + + Mz+cUcJxVYNH1PgH1HQ1lms9b/w6rFkgovMaKX/MFfs= + + + Headers/SDL_sensor.h + + hash2 + + hkGEpyGOUWQhmMkuMasy86uqDchGDP1O8OLMic0d45M= + + + Headers/SDL_stdinc.h + + hash2 + + 1lQYyQZpVGCCIEVg1wB60YfE/4v9zVXcNgevbNJRLPs= + + + Headers/SDL_storage.h + + hash2 + + oxSWVHUbbqMKvx1QBuV39bmyH+VFJj/wE9axnBIA0t4= + + + Headers/SDL_surface.h + + hash2 + + Js/qrm2ltYV2bTT/AUSXIgbmPDb21TuhNGd+j91G6Bs= + + + Headers/SDL_system.h + + hash2 + + j+vc/6qa/tWwnNVuxFtl/+ZasjDpFiKIj/SWs9WvmoA= + + + Headers/SDL_thread.h + + hash2 + + zNaMperhXe4mP0ZQ9LMd/CewmlKkw4xTJpKu7FlubnA= + + + Headers/SDL_time.h + + hash2 + + 2uMjroK2pJQqTpQYR37U8oTurEuBWWavK4ypNIQrjiI= + + + Headers/SDL_timer.h + + hash2 + + 5hkyTURkMquzzC9SGKwImyNFwA5FTsUrX8cj8Tfkvzw= + + + Headers/SDL_touch.h + + hash2 + + IkjbfrMdhQ3G93hAl6yyUMG6/mUIs+kVUEeP//1GUmE= + + + Headers/SDL_tray.h + + hash2 + + KA3SCxpjMIcM5EeEHC6F3o9/5CFr8kAVvsd8Ra+pUms= + + + Headers/SDL_version.h + + hash2 + + 227opDjmxbL8YKwXKqGjwoVvSgAOjqD/x5Gz0fDdC7A= + + + Headers/SDL_video.h + + hash2 + + Yb5Cg96tQZZ0ErDNn2e33TSvsXYbcUYgShi8M3jkjHk= + + + Headers/SDL_vulkan.h + + hash2 + + yHTw0Wf4WcYGEJtGQKPo0qMY51hlnmVhLCebseJiLwg= + + + INSTALL.md + + hash2 + + cfN7quEEdthPBp+Ef9Fnvue8PyOFBgmdeNoftdFDzR8= + + + LICENSE.txt + + hash2 + + l/NbMCs2FoDsHokeldLVIJe7lav/NhQ0kW2Z3BMF8Sc= + + + README.md + + hash2 + + QboZO+koFZBptSlJqxoTwskW+z99BRNKDR6cxw1Mfrg= + + + default.metallib + + hash2 + + PSUqtOrLf2r9qSQ2Yu1rPWW+70REC6dMQXIXDat+ows= + + + + rules + + ^.* + + ^.*\.lproj/ + + optional + + weight + 1000 + + ^.*\.lproj/locversion.plist$ + + omit + + weight + 1100 + + ^Base\.lproj/ + + weight + 1010 + + ^version.plist$ + + + rules2 + + .*\.dSYM($|/) + + weight + 11 + + ^(.*/)?\.DS_Store$ + + omit + + weight + 2000 + + ^.* + + ^.*\.lproj/ + + optional + + weight + 1000 + + ^.*\.lproj/locversion.plist$ + + omit + + weight + 1100 + + ^Base\.lproj/ + + weight + 1010 + + ^Info\.plist$ + + omit + + weight + 20 + + ^PkgInfo$ + + omit + + weight + 20 + + ^embedded\.provisionprofile$ + + weight + 20 + + ^version\.plist$ + + weight + 20 + + + + diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/compile_shaders.sh b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/compile_shaders.sh deleted file mode 100755 index ef5e744..0000000 --- a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/compile_shaders.sh +++ /dev/null @@ -1,68 +0,0 @@ -#!/bin/bash - -set -x -set -e -cd `dirname "$0"` - -shadernames=(FullscreenVert BlitFrom2D BlitFrom2DArray BlitFrom3D BlitFromCube) - -generate_shaders() -{ - fileplatform=$1 - compileplatform=$2 - sdkplatform=$3 - minversion=$4 - - for shadername in "${shadernames[@]}"; do - xcrun -sdk $sdkplatform metal -c -std=$compileplatform-metal1.1 -m$sdkplatform-version-min=$minversion -Wall -O3 -D COMPILE_$shadername -o ./$shadername.air ./Metal_Blit.metal || exit $? - xcrun -sdk $sdkplatform metallib -o $shadername.metallib $shadername.air || exit $? - xxd -i $shadername.metallib | perl -w -p -e 's/\Aunsigned /const unsigned /;' >./${shadername}_$fileplatform.h - rm -f $shadername.air $shadername.metallib - done -} - -generate_shaders macos macos macosx 10.11 -generate_shaders ios ios iphoneos 8.0 -generate_shaders iphonesimulator ios iphonesimulator 8.0 -generate_shaders tvos ios appletvos 9.0 -generate_shaders tvsimulator ios appletvsimulator 9.0 - -# Bundle together one mega-header -catShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - cat ${shadername}_$target.h >> Metal_Blit.h - done -} - -rm -f Metal_Blit.h -echo "#if defined(SDL_PLATFORM_IOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders iphonesimulator - echo "#else" >> Metal_Blit.h - catShaders ios - echo "#endif" >> Metal_Blit.h -echo "#elif defined(SDL_PLATFORM_TVOS)" >> Metal_Blit.h - echo "#if TARGET_OS_SIMULATOR" >> Metal_Blit.h - catShaders tvsimulator - echo "#else" >> Metal_Blit.h - catShaders tvos - echo "#endif" >> Metal_Blit.h -echo "#else" >> Metal_Blit.h - catShaders macos -echo "#endif" >> Metal_Blit.h - -# Clean up -cleanupShaders() -{ - target=$1 - for shadername in "${shadernames[@]}"; do - rm -f ${shadername}_$target.h - done -} -cleanupShaders iphonesimulator -cleanupShaders ios -cleanupShaders tvsimulator -cleanupShaders tvos -cleanupShaders macos \ No newline at end of file diff --git a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/default.metallib b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/default.metallib index 74fdb75..4735a3e 100644 Binary files a/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/default.metallib and b/Frameworks/SDL3.xcframework/tvos-arm64_x86_64-simulator/SDL3.framework/default.metallib differ